...

Text file src/k8s.io/apiextensions-apiserver/examples/client-go/README.md

Documentation: k8s.io/apiextensions-apiserver/examples/client-go

     1# Custom Resource Example
     2
     3**Note:** CustomResourceDefinition is the successor of the deprecated ThirdPartyResource.
     4
     5This particular example demonstrates how to generate a client for CustomResources using [`k8s.io/code-generator`](https://github.com/kubernetes/code-generator). The clientset can
     6be generated using the `./hack/update-codegen.sh` script.
     7
     8The `update-codegen` script will automatically generate the following files and
     9directories:
    10
    11* `pkg/apis/cr/v1/zz_generated.deepcopy.go`
    12* `pkg/client/`
    13
    14The following code-generators are used:
    15
    16* `deepcopy-gen` - creates a method `func (t* T) DeepCopy() *T` for each type T
    17* `client-gen` - creates typed clientsets for CustomResource APIGroups
    18* `informer-gen` - creates informers for CustomResources which offer an event based
    19interface to react on changes of CustomResources on the server
    20* `lister-gen` - creates listers for CustomResources which offer a read-only caching layer for GET and LIST requests.
    21
    22Changes should not be made to these files manually, and when creating your own
    23controller based off of this implementation you should not copy these files and
    24instead run the `update-codegen` script to generate your own.
    25
    26Please see [`k8s.io/sample-controller`](https://github.com/kubernetes/sample-controller) for an example
    27controller for CustomResources using the generated client.
    28
    29## Use Cases
    30
    31CustomResourceDefinitions can be used to implement custom resource types for your Kubernetes cluster.
    32These act like most other Resources in Kubernetes, and may be `kubectl apply`'d, etc.
    33
    34Some example use cases:
    35
    36* Provisioning/Management of external datastores/databases (eg. CloudSQL/RDS instances)
    37* Higher level abstractions around Kubernetes primitives (eg. a single Resource to define an etcd cluster, backed by a Service and a ReplicationController)
    38
    39## Defining types
    40
    41Each instance of your custom resource has an attached Spec, which should be defined via a `struct{}` to provide data format validation.
    42In practice, this Spec is arbitrary key-value data that specifies the configuration/behavior of your Resource.
    43
    44For example, if you were implementing a custom resource for a Database, you might provide a DatabaseSpec like the following:
    45
    46``` go
    47type DatabaseSpec struct {
    48	Databases []string `json:"databases"`
    49	Users     []User   `json:"users"`
    50	Version   string   `json:"version"`
    51}
    52
    53type User struct {
    54	Name     string `json:"name"`
    55	Password string `json:"password"`
    56}
    57```

View as plain text