From bd1ddd32d8da612784716cd64fe5439da1bd461f Mon Sep 17 00:00:00 2001 From: Clayton Coleman Date: Fri, 22 Apr 2016 11:48:58 -0400 Subject: [PATCH] Protobuf doc changes --- docs/devel/adding-an-APIGroup.md | 5 +++++ docs/devel/api-conventions.md | 8 +++++--- docs/devel/api_changes.md | 17 +++++++++++++++++ 3 files changed, 27 insertions(+), 3 deletions(-) diff --git a/docs/devel/adding-an-APIGroup.md b/docs/devel/adding-an-APIGroup.md index dec5d3f0cb..2732ffa540 100644 --- a/docs/devel/adding-an-APIGroup.md +++ b/docs/devel/adding-an-APIGroup.md @@ -64,6 +64,11 @@ Step 2 and 3 are mechanical, we plan on autogenerate these using the cmd/libs/go 1. Touch types.generated.go in pkg/apis/``{/, ``}; 2. Run hack/update-codecgen.sh. +3. Generate protobuf objects: + + 1. Add your group to `cmd/libs/go2idl/go-to-protobuf/protobuf/cmd.go` to `New()` in the `Packages` field + 2. Run hack/update-generated-protobuf.sh + ### Client (optional): We are overhauling pkg/client, so this section might be outdated; see [#15730](https://github.com/kubernetes/kubernetes/pull/15730) for how the client package might evolve. Currently, to add your group to the client package, you need to diff --git a/docs/devel/api-conventions.md b/docs/devel/api-conventions.md index 343800afe9..10dad7723c 100644 --- a/docs/devel/api-conventions.md +++ b/docs/devel/api-conventions.md @@ -34,7 +34,7 @@ Documentation for other releases can be found at API Conventions =============== -Updated: 10/8/2015 +Updated: 4/22/2016 *This document is oriented at users who want a deeper understanding of the Kubernetes API structure, and developers wanting to extend the Kubernetes API. An introduction to @@ -497,6 +497,8 @@ resourceVersion may be used as a precondition for other operations (e.g., GET, D APIs may return alternative representations of any resource in response to an Accept header or under alternative endpoints, but the default serialization for input and output of API responses MUST be JSON. +Protobuf serialization of API objects are currently **EXPERIMENTAL** and will change without notice. + All dates should be serialized as RFC3339 strings. ## Units @@ -617,13 +619,13 @@ $ curl -v -k -H "Authorization: Bearer WhCDvq4VPpYhrcfmF6ei7V9qlbqTubUc" https:/ > Host: 10.240.122.184 > Accept: */* > Authorization: Bearer WhCDvq4VPpYhrcfmF6ei7V9qlbqTubUc -> +> < HTTP/1.1 404 Not Found < Content-Type: application/json < Date: Wed, 20 May 2015 18:10:42 GMT < Content-Length: 232 -< +< { "kind": "Status", "apiVersion": "v1", diff --git a/docs/devel/api_changes.md b/docs/devel/api_changes.md index 987d557626..703b174318 100644 --- a/docs/devel/api_changes.md +++ b/docs/devel/api_changes.md @@ -51,6 +51,7 @@ found at [API Conventions](api-conventions.md). - [Edit types.go](#edit-typesgo) - [Edit validation.go](#edit-validationgo) - [Edit version conversions](#edit-version-conversions) + - [Generate protobuf objects](#generate-protobuf-objects) - [Edit json (un)marshaling code](#edit-json-unmarshaling-code) - [Making a new API Group](#making-a-new-api-group) - [Update the fuzzer](#update-the-fuzzer) @@ -472,6 +473,22 @@ generator to create it from scratch. Unsurprisingly, adding manually written conversion also requires you to add tests to `pkg/api//conversion_test.go`. +## Generate protobuf objects + +For any core API object, we also need to generate the Protobuf IDL and marshallers. +That generation is done with + +```sh +hack/update-generated-protobuf.sh +``` + +The vast majority of objects will not need any consideration when converting +to protobuf, but be aware that if you depend on a Golang type in the standard +library there may be additional work requried, although in practice we typically +use our own equivalents for JSON serialization. The `pkg/api/serialization_test.go` +will verify that your protobuf serialization preserves all fields - be sure to +run it several times to ensure there are no incompletely calculated fields. + ## Edit json (un)marshaling code We are auto-generating code for marshaling and unmarshaling json representation