sigs.k8s.io/kubebuilder/v3@v3.14.0/docs/using_an_external_type.md (about)

     1  # Using an External Type
     2  
     3  
     4  # Introduction
     5  
     6  There are several different external types that may be referenced when writing a controller.
     7  * A Custom Resource Definition (CRD) that is defined in the current project `kubebuilder create api`.
     8  * A Core Kubernetes Resources eg. `kubebuilder create api --group apps --version v1 --kind Deployment`.
     9  * A CRD that is created and installed in another project.
    10  * 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.
    11  
    12  Currently Kubebuilder handles the first two, CRDs and Core Resources, seamlessly.  External CRDs and CRs created via Aggregation must be scaffolded manually.
    13  
    14  In order to use a Kubernetes Custom Resource that has been defined in another project
    15  you will need to have several items of information.
    16  * The Domain of the CR
    17  * The Group under the Domain 
    18  * The Go import path of the CR Type definition.
    19  
    20  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.
    21  
    22  This document uses `my` and `their` prefixes as a naming convention for repos, groups, and types to clearly distinguish between your own project and the external one you are referencing.
    23  
    24  Example external API Aggregation directory structure
    25  ```
    26  github.com
    27      ├── theiruser
    28          ├── theirproject
    29              ├── apis
    30                  ├── theirgroup
    31                     ├── doc.go
    32                     ├── install
    33                     │   ├── install.go
    34                     ├── v1alpha1
    35                     │   ├── doc.go
    36                     │   ├── register.go
    37                     │   ├── types.go
    38                     │   ├── zz_generated.deepcopy.go
    39  ```
    40  
    41  In the case above the import path would be `github.com/theiruser/theirproject/apis/theirgroup/v1alpha1`
    42  
    43  ### Create a project
    44  
    45  ```
    46  kubebuilder init --domain $APIDOMAIN --owner "MyCompany"
    47  ```
    48  
    49  ### Add a controller
    50  
    51  be sure to answer no when it asks if you would like to create an api? [Y/n]
    52  ```
    53  kubebuilder create api --group mygroup --version $APIVERSION --kind MyKind
    54  
    55  ```
    56  
    57  ## Edit the API files.
    58  
    59  ### Register your Types
    60  
    61  Edit the following file to the pkg/apis directory to append their `AddToScheme` to your `AddToSchemes`:
    62  
    63  file: pkg/apis/mytype_addtoscheme.go
    64  ```
    65  package apis
    66  
    67  import (
    68  	mygroupv1alpha1 "github.com/myuser/myrepo/apis/mygroup/v1alpha1"
    69  	theirgroupv1alpha1 "github.com/theiruser/theirproject/apis/theirgroup/v1alpha1"
    70  )
    71  
    72  func init() {
    73  	// Register the types with the Scheme so the components can map objects 
    74  	// to GroupVersionKinds and back
    75  	AddToSchemes = append(
    76  	  AddToSchemes, 
    77  	  mygroupv1alpha1.SchemeBuilder.AddToScheme,
    78  	  theirgroupv1alpha1.SchemeBuilder.AddToScheme,
    79  	)
    80  }
    81  
    82  ```
    83  
    84  ## Edit the Controller files
    85  
    86  ### Use the correct imports for your API
    87  
    88  file: pkg/controllers/mytype_controller.go
    89  ```
    90  import (
    91  	mygroupv1alpha1 "github.com/myuser/myrepo/apis/mygroup/v1alpha1"
    92  	theirgroupv1alpha1 "github.com/theiruser/theirproject/apis/theirgroup/v1alpha1"
    93  )
    94  ```
    95  
    96  ### Update dependencies
    97  
    98  ```
    99  dep ensure --add
   100  ```
   101  
   102  ## Prepare for testing
   103  
   104  #### Register your resource
   105  
   106  Edit the `CRDDirectoryPaths` in your test suite by appending the path to their CRDs:
   107  
   108  file pkg/controllers/my_kind_controller_suite_test.go
   109  ```
   110  var cfg *rest.Config
   111  
   112  func TestMain(m *testing.M) {
   113  	// Get a config to talk to the apiserver
   114  	t := &envtest.Environment{
   115  		Config:             cfg,
   116  		CRDDirectoryPaths:  []string{
   117  		  filepath.Join("..", "..", "..", "config", "crds"),
   118  		  filepath.Join("..", "..", "..", "vendor", "github.com", "theiruser", "theirproject", "config", "crds"),
   119          },
   120  		UseExistingCluster: true,
   121  	}
   122  
   123  	apis.AddToScheme(scheme.Scheme)
   124  
   125  	var err error
   126  	if cfg, err = t.Start(); err != nil {
   127  		log.Fatal(err)
   128  	}
   129  
   130  	code := m.Run()
   131  	t.Stop()
   132  	os.Exit(code)
   133  }
   134  
   135  ```
   136  
   137  ## Helpful Tips
   138  
   139  ### Locate your domain and group variables
   140  
   141  The following kubectl commands may be useful
   142  
   143  ```
   144  kubectl api-resources --verbs=list -o name
   145  
   146  kubectl api-resources --verbs=list -o name | grep mydomain.com
   147  ```
   148