Add glossary term for CRD #6594

Bubblemelon · 2017-12-05T21:51:57Z

This resolves part of issue #5993, adding Custom Resource Definition replacing Third Party Resource.

This change is

Custom Resource Definition, that replaces Third Party Resources.

k8s-ci-robot · 2017-12-05T21:52:09Z

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.

If you've already signed a CLA, it's possible we don't have your GitHub username or you're using a different email address. Check your existing CLA data and verify that your email is set on your git commits.
If you signed the CLA as a corporation, please sign in with your organization's credentials at https://identity.linuxfoundation.org/projects/cncf to be authorized.
If you have done the above and are still having issues with the CLA being reported as unsigned, please email the CNCF helpdesk: helpdesk@rt.linuxfoundation.org

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.

Bradamant3 · 2017-12-05T21:58:42Z

@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 ...)

Bubblemelon · 2017-12-05T22:00:19Z

I have just finished signing the cla terms and agreements.

Bradamant3

Difficult to make this one short, complete, and accurate, but check out individual line comments for some suggestions.

Bradamant3 · 2017-12-05T22:00:30Z

_data/glossary/customresourcedefinition.yaml

+- fundamental
+- operation
+short-description: >
+  A custom resource definition is the representation of a customization of a particular Kubernetes installation.


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)

Bradamant3 · 2017-12-05T22:02:48Z

_data/glossary/customresourcedefinition.yaml

+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.


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!

Bradamant3 · 2017-12-05T22:04:40Z

Oh, and the munged syntax I think is with the tag location.

Bubblemelon · 2017-12-05T22:06:09Z

Hello @Bradamant3, thanks for giving the the heads up. There's some silly formating errors. :)

Minor formating error

k8sio-netlify-preview-bot · 2017-12-05T22:08:41Z

Deploy preview ready!

Built with commit 312d686

https://deploy-preview-6594--kubernetes-io-master-staging.netlify.com

Bubblemelon · 2017-12-05T22:17:08Z

turns out the id: key is necessary !

missing id key

Bubblemelon · 2017-12-05T22:22:02Z

Hi @Bradamant3 , mind giving me clues on how to pass this travis-ci check ?

deleted aka key

Bradamant3

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.

tonglil · 2017-12-05T23:05:16Z

_data/glossary/customresourcedefinition.yaml

+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.


that is specified reads awkwardly, probably can be removed.

okay noted!

nikhita

@Bubblemelon Thanks for submitting this PR! 🎉

Left a bunch of comments but the PR is awesome as-is. 😄

nikhita · 2017-12-21T09:59:34Z

_data/glossary/customresourcedefinition.yaml

@@ -0,0 +1,10 @@
+id: Custom Resource Definition


CustomResourceDefinition is one word.

Done ! 😄

nikhita · 2017-12-21T09:59:52Z

_data/glossary/customresourcedefinition.yaml

@@ -0,0 +1,10 @@
+id: Custom Resource Definition
+name: Custom Resource Definition


CustomResourceDefinition is one word.

nikhita · 2017-12-21T10:01:38Z

_data/glossary/customresourcedefinition.yaml

+name: Custom Resource Definition
+tags:
+- fundamental
+- operation


Also extension.

nikhita · 2017-12-21T10:02:06Z

_data/glossary/customresourcedefinition.yaml

+tags:
+- fundamental
+- operation
+full-link: docs/tasks/access-kubernetes-api/migrate-third-party-resource/


This link mainly talks about TPRs. Please link to https://kubernetes.io/docs/tasks/access-kubernetes-api/extend-api-custom-resource-definitions/.

nikhita · 2017-12-21T10:03:51Z

_data/glossary/customresourcedefinition.yaml

+- 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.


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. :)

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.

nikhita · 2017-12-21T10:05:21Z

_data/glossary/customresourcedefinition.yaml

+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.


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.

nikhita · 2017-12-21T10:07:33Z

_data/glossary/customresourcedefinition.yaml

+tags:
+- fundamental
+- operation
+full-link: docs/tasks/access-kubernetes-api/migrate-third-party-resource/


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)

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)

Hi @nikhita ! Thanks for providing all these great suggestions. The _example.yml was particularly helpful. 😄

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 😄

I'll leave the related section aside for now until someone responds to your request on this issue.

Sure, makes sense. 👍

nikhita · 2017-12-21T10:21:26Z

@Bubblemelon Can you update the PR title to say something like Add glossary term for CRD? Would be easier to search/link issues later. :)

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.

nikhita · 2018-01-04T04:26:30Z

@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.

Bradamant3

Still needs some more work. This is a difficult item -- kudos for taking it on!

Bradamant3 · 2018-01-11T18:31:27Z

_data/glossary/customresourcedefinition.yaml

+- 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.


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.

Bradamant3 · 2018-02-16T16:41:36Z

/lgtm
Merging bc there are still needed changes, but this is a first-time contributor from the docs summit at Kubecon Austin 2017. It's embarrassingly late, and there are too many review comments for a newcomer to parse easily. n.b. let's do a better job of steering folks who are new to both docs and K8s toward more straightforward glossary terms. CRDs are difficult. Thanks @Bubblemelon for getting us started here!

k8s-ci-robot · 2018-02-16T16:41:42Z

[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:

~~OWNERS~~ [Bradamant3]

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

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

d879d4f

Custom Resource Definition, that replaces Third Party Resources.

k8s-github-robot assigned Bradamant3 Dec 5, 2017

k8s-ci-robot added the size/S Denotes a PR that changes 10-29 lines, ignoring generated files. label Dec 5, 2017

k8s-ci-robot added the cncf-cla: no Indicates the PR's author has not signed the CNCF CLA. label Dec 5, 2017

k8s-ci-robot added cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. and removed cncf-cla: no Indicates the PR's author has not signed the CNCF CLA. labels Dec 5, 2017

Bradamant3 suggested changes Dec 5, 2017

View reviewed changes

Update customresourcedefinition.yaml

45a5e6e

Minor formating error

Update customresourcedefinition.yaml

5e0be81

missing id key

Update customresourcedefinition.yaml

688bce0

deleted aka key

Bradamant3 suggested changes Dec 5, 2017

View reviewed changes

tonglil reviewed Dec 5, 2017

View reviewed changes

nikhita reviewed Dec 21, 2017

View reviewed changes

tengqm changed the title ~~Resolving part of issue #5993~~ Add glossary term for CRD Dec 25, 2017

Update customresourcedefinition.yaml

312d686

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.

Bradamant3 previously requested changes Jan 11, 2018

View reviewed changes

Bradamant3 closed this Feb 16, 2018

Bradamant3 reopened this Feb 16, 2018

k8s-ci-robot added the lgtm "Looks good to me", indicates that a PR is ready to be merged. label Feb 16, 2018

k8s-ci-robot added the approved Indicates a PR has been approved by an approver from all required OWNERS files. label Feb 16, 2018

k8s-ci-robot merged commit 01a981b into kubernetes:master Feb 16, 2018

Bradamant3 mentioned this pull request Feb 16, 2018

fix up CRD glossary term #7428

Merged

Bubblemelon mentioned this pull request Apr 1, 2019

REQUEST: New membership for bubblemelon kubernetes/org#670

Closed

6 tasks

		@@ -0,0 +1,10 @@
		id: Custom Resource Definition
		name: Custom Resource Definition

Add glossary term for CRD #6594

Add glossary term for CRD #6594

Conversation

Bubblemelon commented Dec 5, 2017 • edited by k8s-reviewable Loading

k8s-ci-robot commented Dec 5, 2017

Bradamant3 commented Dec 5, 2017

Bubblemelon commented Dec 5, 2017

Bradamant3 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Bradamant3 commented Dec 5, 2017

Bubblemelon commented Dec 5, 2017

k8sio-netlify-preview-bot commented Dec 5, 2017 • edited Loading

Bubblemelon commented Dec 5, 2017

Bubblemelon commented Dec 5, 2017

Bradamant3 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

nikhita left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

nikhita Dec 21, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

nikhita Dec 21, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

nikhita Dec 21, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

nikhita commented Dec 21, 2017

nikhita commented Jan 4, 2018 • edited Loading

Bradamant3 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Bradamant3 commented Feb 16, 2018

k8s-ci-robot commented Feb 16, 2018

Bubblemelon commented Dec 5, 2017 •

edited by k8s-reviewable

Loading

k8sio-netlify-preview-bot commented Dec 5, 2017 •

edited

Loading

nikhita Dec 21, 2017 •

edited

Loading

nikhita Dec 21, 2017 •

edited

Loading

nikhita Dec 21, 2017 •

edited

Loading

nikhita commented Jan 4, 2018 •

edited

Loading