-
Notifications
You must be signed in to change notification settings - Fork 1.1k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #363 from jkev53/using_an_external_type
Document adding an external type
- Loading branch information
Showing
1 changed file
with
139 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,139 @@ | ||
# Using an external Type | ||
|
||
|
||
# Introduction | ||
|
||
There are several different external types that may be referenced when writing a controller. | ||
* A Custom Resource Definition (CRD) that is defined in the current project `kubebuilder create api`. | ||
* A Core Kubernetes Resources eg. `kubebuilder create api --group apps --version v1 --kind Deployment`. | ||
* A CRD that is created and installed in another project. | ||
* A CR defined via an API Aggregation (AA). Aggregated APIs are subordinate APIServers that sit behind the primary API server, which acts as a proxy. | ||
|
||
Currrently Kubebuilder handles the first two, CRDs and Core Resources, seamlessly. External CRDs and CRs created via Aggregation must be scaffolded manually. | ||
|
||
In order to use a Kubernetes Custom Resource that has been defined in another project | ||
you will need to have several items of information. | ||
* The Domain of the CR | ||
* The Group under the Domain | ||
* The Go import path of the CR Type definition. | ||
|
||
The Domain and Group variables have been discussed in other parts of the documentation. The import path would be located in the project that installs the CR. | ||
|
||
Example API Aggregation directory structure | ||
``` | ||
github.com | ||
├── example | ||
├── myproject | ||
├── apis | ||
├── mygroup | ||
├── doc.go | ||
├── install | ||
│ ├── install.go | ||
├── v1alpha1 | ||
│ ├── doc.go | ||
│ ├── register.go | ||
│ ├── types.go | ||
│ ├── zz_generated.deepcopy.go | ||
``` | ||
|
||
In the case above the import path would be `github.com/example/myproject/apis/mygroup/v1alpha1` | ||
|
||
### Create a project | ||
|
||
``` | ||
kubebuilder init --domain $APIDOMAIN --owner "MyCompany" | ||
``` | ||
|
||
### Add a controller | ||
|
||
be sure to answer no when it asks if you would like to create an api? [Y/n] | ||
``` | ||
kubebuilder create api --group $APIGROUP --version $APIVERSION --kind MyKind | ||
``` | ||
|
||
## Edit the Api files. | ||
|
||
### Register your Types | ||
|
||
Add the following file to the pkg/apis directory | ||
|
||
file: pkg/apis/mytype_addtoscheme.go | ||
``` | ||
package apis | ||
import ( | ||
mygroupv1alpha1 "github.com/username/myapirepo/apis/mygroup/v1alpha1" | ||
) | ||
func init() { | ||
// Register the types with the Scheme so the components can map objects | ||
// to GroupVersionKinds and back | ||
AddToSchemes = append(AddToSchemes, mygroupv1alpha1.AddToScheme) | ||
} | ||
``` | ||
|
||
## Edit the Controller files | ||
|
||
### Use the correct import for your api | ||
|
||
file: pkg/controllers/mytype_controller.go | ||
``` | ||
import mygroupv1alpha1 "github.com/example/myproject/apis/mygroup/v1alpha1" | ||
``` | ||
|
||
## Prepare for testing | ||
|
||
#### Register your resource | ||
|
||
Add the registration code to the test framework | ||
|
||
file pkg/controller/my_agg_resource_controller_suite_test.go | ||
``` | ||
import ( | ||
) | ||
var cfg *rest.Config | ||
func TestMain(m *testing.M) { | ||
// Get a config to talk to the apiserver | ||
t := &envtest.Environment{ | ||
Config: cfg, | ||
CRDDirectoryPaths: []string{filepath.Join("..", "..", "..", "config", "crds")}, | ||
UseExistingCluster: true, | ||
} | ||
apis.AddToScheme(scheme.Scheme) | ||
var err error | ||
if cfg, err = t.Start(); err != nil { | ||
log.Fatal(err) | ||
} | ||
code := m.Run() | ||
t.Stop() | ||
os.Exit(code) | ||
} | ||
``` | ||
|
||
### Update dependencies | ||
|
||
``` | ||
dep ensure --add | ||
``` | ||
|
||
## Helpful Tips | ||
|
||
### Locate your domain and group variables | ||
|
||
The following kubectl commands may be useful | ||
|
||
``` | ||
kubectl api-resources --verbs=list -o name | ||
kubectl api-resources --verbs=list -o name | grep mydomain.com | ||
``` | ||
|