See #3955 and #1451 (comment).

Clients generating specific objects, such as kubectl run-container, should target a specific API version (or multiple specific versions).

Generic clients shouldn't be versioned. They should only get the schema via swagger.

On the timing of when to fix this. Goal is we want pkg/client users to work with versioned api types instead of unversioned types. So at some point we'll want to alias api to api/v1beta3 (in e.g. test code).

When we have v1beta3 as default but before we've accumulated many changes, then the diff between internal types and v1beta3 types should be minimized. ...so now would be a good time to think about doing this, actually.

cc @vishh

@lavalamp: My understanding was that we are are doing this before v1.0.

On Wed, Apr 1, 2015 at 10:24 AM, Brian Grant notifications@github.com
wrote:

cc @vishh https://github.com/vishh

—
Reply to this email directly or view it on GitHub
#4874 (comment)
.

I want to argue for a prio boost on this. If we go 1.0 and we leave internal structs exposed, we're as good as frozen.

We should either

a) hide all the internal structs and have purely versioned client libs (how do we get DeltaFIFO and cache and controller framework etc for versioned?)
b) use swagger codegen to generate Go libs
c) not have a Go client library at all

Almost all of our own components would be better off with versioned interfaces, but I think all the work that has been done on client libs and controller framework has to apply.

I propose P2, enhancement, v1.0 milestone. Needs an owner ASAP.

Casting aside the fact the either is not a ternary operator, if nobody else want to take this on then I'd be happy to help esp. if we follow Daniel's proposal to have versioned Go client libraries but address the issues in (a). I think Brain said there were some technicalities to do with (b) w.r.t. encoding for a few fields but perhaps these could be overcome somehow. (c) would be a shame.

One option is to get an intern to work on (b) but it might be too little
too late

On Fri, Apr 10, 2015 at 12:04 AM, Satnam Singh notifications@github.com
wrote:

Casting aside the fact the either is not a ternary operator, if nobody
else want to take this on then I'd be happy to help esp. if follow Daniel's
proposal to have versioned Go client libraries but address the issues in
(a). I think Brain said there were some technicalities to do with (b)
w.r.t. encoding for a few fields but perhaps these could be overcome
somehow. (c) would be a shame.

—
Reply to this email directly or view it on GitHub
#4874 (comment)
.

Swagger codegen for Go doesn't yet exist. And it doesn't yet work for any language for our API AFAIK.

There are no intrinsic blockers to codegen that I'm aware of. Some of the fields that require custom marshaling/unmarshaling would need custom client code, but that doesn't seem like a big deal. I don't think most clients would need complicated types, such as Resource Quantity. Users could just provide the strings.

If we have time, this would be great to do sooner rather than later. The problem will get bigger over time. I'm not sure there is a hard deadline, though.

Indeed swagger codegen for Go seems to be an open issue: swagger-api/swagger-codegen#325

@bgrant0607 : let me be sure about what you mean. You mean "write a program that parses the swagger spec and spits out a Go client library?" Or do you mean something else?

My concern is that, based on our own experiences and the evolution of the
client-side caches and watch helper libs, the swagger generated client API
will be insufficient.

On Fri, Apr 10, 2015 at 9:23 AM, Satnam Singh notifications@github.com
wrote:

Indeed swagger codegen for Go seems to be an open issue:
swagger-api/swagger-codegen#325
swagger-api/swagger-codegen#325

@bgrant0607 https://github.com/bgrant0607 : let me be sure about what
you mean. You mean "write a program that parses the swagger spec and spits
out a Go client library?" Or do you mean something else?

—
Reply to this email directly or view it on GitHub
#4874 (comment)
.

/subscribe

If this is something that needs attention soon thenI am happy to direct some energy in this direction, although that may not please Tim since I am supposed to be learning about networking.

Package factoring to consider: #7584.

OK. Time to do this. The motivation is so that people can import pkg/client/v1 and have code that will continue to build against head without changes as long as v1 is supported.

Proposed factoring:

• pkg/client/config
  • This has everything to do with certs, setup, etc.
• pkg/client/rest
  • RESTClient moves here
• pkg/client/unversioned
  • the current client.Client struct and interfaces move here.
• pkg/client/v1
  • A copy of unversioned, but using pkg/api/v1 instead of pkg/api

I propose doing this in a few steps.

1. Copy pkg/client to pkg/client/v1 AND pkg/client/unversioned.
   1. Change the import lines in pkg/client/v1 to go to pkg/api/v1.
2. Change references in the rest of the codebase to the appropriate client.
   1. I know @bgrant0607 would love it if nothing ended up referencing pkg/client/unversioned. I wouldn't prioritize this at the moment. It's still a net improvement in that it will be clearly marked what uses v1 and what doesn't.
3. Extract common code into pkg/client/rest & pkg/client/config
   1. This can happen in parallel with step 2.
4. Remove all client like things from pkg/client once 2 is finished.

What about:

• experimental client
• pkg/client/cache
• pkg/client/metrics
• pkg/client/record
• pkg/kubectl/resource
• Make it easy to include a kubernetes client library in a separate Go project #5660
• Versioned API objects should be in a self-contained package #7584

The above WIP PR #13098 is a mess. To directly address those issues, I would
like to put RESTClient and Request into their own package that has no
dependencies on a version or group. Currently request.go has some custom
field selector filtering logic that depends on the version that I need to
understand. I think this would still leave it dependent on api.Status, but
we don't change that across versions/groups. I would also like to change it to
take the codec on each request instead of being embedded in the client. This
could allow multiple groups/versions to use the same RESTClient.

I would also like to move the VersionInterface and functionality into this
package as it is also independent of groups/versions.

There are some things which are in this package that I'm not sure belong in
the API client, but I don't know where I would put them. I'm open to
suggestions on:

• KubeletClient
• ContainerInfoGetter
• flags.go

With those changes, the code left in the actual versioned clients should be
mostly boiler plate calls into this new package with the appropriate codecs
and type assertions on the return values.

@bgrant0607

My opinions on your concerns...

• experimental client:
  Should be it's own package separate from the versioned client.
• pkg/client/cache:
  We probably need to version the top level interface of this package as well.
  Seems ripe for internal packages + code generation.
• pkg/client/metrics:
  I don't see a problem with this one. Is it version dependent in some way
  that I don't see?
• pkg/client/record:
  What is the use case for this? Is it something a customer needs? Or
  something we need internally? It might be ok to use runtime.Object
  instead of concrete events for this.
• pkg/kubectl/resource:
  Still looking in to this one...
• Make it easy to include a kubernetes client library in a separate Go project #5660 and Versioned API objects should be in a self-contained package #7584:
  These goals are a way off. I think it would require a huge cleanup with our
  many "schemes" and "codecs." I think the biggest step would be to completely
  separate encoding/decoding from conversion. The only ones that should need
  conversion are the API server and special utilities for upgrading various
  resources. Another option is to just abandon the schemes and codecs in the
  client code and roll our own simple ones. That with a types only package
  from the API could make this achievable.

cc: @caesarxuchao

I think pkg/client/cache is and should remain version agnostic. It's a general caching layer and should work with runtime.Objects.

Currently request.go has some custom field selector filtering logic that depends on the version that I need to understand.

Should be moved into the high level client, or a generic high-ish level client (like kubectl's builder)

I would also like to change it to take the codec on each request instead of being embedded in the client. This could allow multiple groups/versions to use the same RESTClient.

I actually think we should leave the codec in the RESTClient. There should be an additional layer under RESTClient, the http connection/transport/cert layer; RESTClients that actually point at the same server can re-use that layer. This should help @smarterclayton with openshift integration.

Other misc thoughts:

• RESTClient needs to become an interface instead of a struct.
• If we have 10 groups with 3 versions each, it becomes infeasible to offer every combination as a typed client. Therefore, we must do one or both of:
  • Offer curated/tested versioned clients, where we select the versions for each group.
  • Switch our deliverable to be a versioned client generator, such that you specify the group/versions you wish and a high level client will be generated for you.

Explicit proposal in #15730

I think if #21408 merges, we can punt the rest of this to the next release.

#21408 has merged, time to punt?

@lavalamp @krousey What remains to be done here?

Clientset is our versioned client. The next step is extract the client lib into its own repo, then vendor it in the main repo, and convert pkg/controllers and pkg/kubelet to use the versioned client.

AFAIK, kubectl should use the dynamic client, @krousey is working on it and have more insight.

@caesarxuchao Is there a tracking issue for "next step is extract the client lib into its own repo"?

@ae6rt, it's #28559

Closing in favor of #29934 as it represents the remaining tasks and is owned by the person actively working on it.