github/kubernetes
1
0
Fork 0
mirror of https://github.com/k3s-io/kubernetes.git synced 2025-08-22 10:06:15 +00:00
Code Issues Projects Releases Wiki Activity

Merge pull request #7481 from erictune/apiprincip

Browse Source 
Add API change suggestions.
This commit is contained in:
Tim Hockin 2015-05-18 16:55:13 -07:00
commit 76f99aab94
1 changed files with 9 additions and 3 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

12
docs/devel/api_changes.md
View File

@ -12,7 +12,7 @@ not all API changes will need all of these steps.
## Operational overview ## Operational overview
It's important to have a high level understanding of the API system used in It is important to have a high level understanding of the API system used in
Kubernetes in order to navigate the rest of this document. Kubernetes in order to navigate the rest of this document.
As mentioned above, the internal representation of an API object is decoupled As mentioned above, the internal representation of an API object is decoupled
@ -24,13 +24,13 @@ a GET involves a great deal of machinery.
The conversion process is logically a "star" with the internal form at the The conversion process is logically a "star" with the internal form at the
center. Every versioned API can be converted to the internal form (and center. Every versioned API can be converted to the internal form (and
vice-versa), but versioned APIs do not convert to other versioned APIs directly. vice-versa), but versioned APIs do not convert to other versioned APIs directly.
This sounds like a heavy process, but in reality we don't intend to keep more This sounds like a heavy process, but in reality we do not intend to keep more
than a small number of versions alive at once. While all of the Kubernetes code than a small number of versions alive at once. While all of the Kubernetes code
operates on the internal structures, they are always converted to a versioned operates on the internal structures, they are always converted to a versioned
form before being written to storage (disk or etcd) or being sent over a wire. form before being written to storage (disk or etcd) or being sent over a wire.
Clients should consume and operate on the versioned APIs exclusively. Clients should consume and operate on the versioned APIs exclusively.
To demonstrate the general process, let's walk through a (hypothetical) example: To demonstrate the general process, here is a (hypothetical) example:
1. A user POSTs a `Pod` object to `/api/v7beta1/...` 1. A user POSTs a `Pod` object to `/api/v7beta1/...`
2. The JSON is unmarshalled into a `v7beta1.Pod` structure 2. The JSON is unmarshalled into a `v7beta1.Pod` structure
@ -176,6 +176,12 @@ If your change includes new fields for which you will need default values, you
need to add cases to `pkg/api/<version>/defaults.go`. Of course, since you need to add cases to `pkg/api/<version>/defaults.go`. Of course, since you
have added code, you have to add a test: `pkg/api/<version>/defaults_test.go`. have added code, you have to add a test: `pkg/api/<version>/defaults_test.go`.
Do use pointers to scalars when you need to distinguish between an unset value
and an an automatic zero value. For example,
`PodSpec.TerminationGracePeriodSeconds` is defined as `*int64` the go type
definition. A zero value means 0 seconds, and a nil value asks the system to
pick a default.
Don't forget to run the tests! Don't forget to run the tests!
### Edit conversion.go ### Edit conversion.go