github/kubernetes
1
0
Fork 0
mirror of https://github.com/k3s-io/kubernetes.git synced 2025-07-30 06:54:01 +00:00
Code Issues Projects Releases Wiki Activity

add to api repo documentation

Browse Source
This commit is contained in:
Daniel Smith 2020-01-29 11:47:38 -08:00
parent cad44602e1
commit 8ce61eef5b
1 changed files with 24 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

24
staging/src/k8s.io/api/README.md
View File

@ -6,6 +6,30 @@ Schema of the external API types that are served by the Kubernetes API server.
This library is the canonical location of the Kubernetes API definition. Most likely interaction with this repository is as a dependency of client-go.
It is published separately to avoid diamond dependency problems for users who
depend on more than one of `k8s.io/client-go`, `k8s.io/apimachinery`,
`k8s.io/apiserver`...
## Recommended Use
We recommend using the go types in this repo. You may serialize them directly to
JSON.
If you want to store or interact with proto-formatted Kubernetes API objects, we
recommend using the "official" serialization stack in `k8s.io/apimachinery`.
Directly serializing these types to proto will not result in data that matches
the wire format or is compatible with other kubernetes ecosystem tools. The
reason is that the wire format includes a magic prefix and an envelope proto.
Please see:
https://kubernetes.io/docs/reference/using-api/api-concepts/#protobuf-encoding
For the same reason, we do not recommend embedding these proto objects within
your own proto definitions. It is better to store Kubernetes objects as byte
arrays, in the wire format, which is self-describing. This permits you to use
either JSON or binary (proto) wire formats without code changes. It will be
difficult for you to operate on both Custom Resources and built-in types
otherwise.
## Compatibility
Branches track Kubernetes branches and are compatible with that repo.