Agree with the approach, and I'd like to take this on as part of my scheduler separation work.

I may quibble with the particular groups, and I'd like it to be possible to put the same resource in multiple groups. (e.g., scheduler and replication controller both need to see pods.)

I think groups can depend on others, they just have to do so over an api connection. And conversely, if a group needs no knowledge of another resource, that resource should not be in that group. So a pod does not need to know about a replication controller or service, and so those should not be in the same group as a pod.

I guess I would structure it a bit differently. My initial thought is that the scheduler endpoint should serve everything the scheduler needs, the replicationController endpoint serves everything the replicationController needs, etc.

I think the possibility of running in an arbitrary API group endpoint should be sufficient to keep the code totally separate all the way down to the storage layer.

Go interfaces make it really easy to write code that will use a resource either over an API connection or a locally served one. The latter comes with efficiency gains, so I don't think we should completely veto it.

I get what you mean now - making an endpoint composed of a set of resources targeted to a consumer, potentially having different security or access pattern constraints. Makes sense.

Local interfaces: For sure - meant purely logical separation, not enforced.

@smarterclayton @lavalamp Sounds pretty good. We also need to split up types.go. We could start by pulling out parts of it that we'd want to use in new APIs, such as the ReasonType constants.

Some concrete examples from OpenShift of how we're using APIGroup now (haven't yet integrated Eric's changes w.r.t. Master and authentication)

https://github.com/openshift/origin/blob/master/pkg/cmd/server/origin/master.go#L178

    var extra []string
    for _, i := range installers {
        extra = append(extra, i.InstallAPI(osMux)...)
    }
    apiserver.NewAPIGroup(storage, v1beta1.Codec, OpenShiftAPIPrefixV1Beta1, latest.SelfLinker).InstallREST(osMux, OpenShiftAPIPrefixV1Beta1)
    apiserver.InstallSupport(osMux)

    handler := http.Handler(osMux)
    if c.RequireAuthentication {
        handler = c.wrapHandlerWithAuthentication(handler)
    }
    if len(c.CORSAllowedOrigins) > 0 {
        handler = apiserver.CORS(handler, c.CORSAllowedOrigins, nil, nil, "true")
    }

    handler = apiserver.RecoverPanics(handler)

    server := &http.Server{
        Addr:           c.BindAddr,
        Handler:        handler,
        ReadTimeout:    5 * time.Minute,
        WriteTimeout:   5 * time.Minute,
        MaxHeaderBytes: 1 << 20,
    }

The first loop there is injecting other API groups into our Mux (for the case when we want to load Kubernetes API as well for our standalone binary). That code is at https://github.com/openshift/origin/blob/master/pkg/cmd/server/kubernetes/master.go#L48

and does:

    apiserver.NewAPIGroup(m.API_v1beta1()).InstallREST(mux, KubeAPIPrefixV1Beta1)
    apiserver.NewAPIGroup(m.API_v1beta2()).InstallREST(mux, KubeAPIPrefixV1Beta2)

    return []string{
        fmt.Sprintf("Started Kubernetes API at %%s%s", KubeAPIPrefixV1Beta1),
        fmt.Sprintf("Started Kubernetes API at %%s%s", KubeAPIPrefixV1Beta2),
    }

So we want to keep api groups separate if possible from being tied to Kubernetes, because we want to be able to

1. Reuse the core apiserver implementation so we have 100% fidelity with the Kube API conventions
2. Add blocks of API functionality in the all-in-one binary (for when you don't have a Kube deployment)
3. Omit certain API groups when we connect to an existing Kube deployment, and handle registering ourselves as a ComponentPlugin when we startup.

Once we have designed ComponentPlugins enough that our pattern works, it seems like the APIs of registered plugins should show up in the central API doc. Each group of versions is a unit, and it would be ideal to install those to a server as a unit so that we can have these consistent patterns.

This is superseded by #3201