Merge pull request #752 from ryanbrainard/external-type-testing-doc

Doc Clarification: Using an External Type

Author: k8s-ci-robot

docs/using_an_external_type.md

@@ -1,4 +1,4 @@
-# Using an external Type
+# Using an External Type
 
 
 # Introduction
@@ -19,13 +19,15 @@ you will need to have several items of information.
 
 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
+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.
+
+Example external API Aggregation directory structure
 ```
 github.com
-    ├── example
-        ├── myproject
+    ├── theiruser
+        ├── theirproject
             ├── apis
-                ├── mygroup
+                ├── theirgroup
                    ├── doc.go
                    ├── install
                    │   ├── install.go
@@ -36,7 +38,7 @@ github.com
                    │   ├── zz_generated.deepcopy.go
 ```
 
-In the case above the import path would be `github.com/example/myproject/apis/mygroup/v1alpha1`
+In the case above the import path would be `github.com/theiruser/theirproject/apis/theirgroup/v1alpha1`
 
 ### Create a project
 
@@ -48,60 +50,73 @@ kubebuilder init --domain $APIDOMAIN --owner "MyCompany"
 
 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
+kubebuilder create api --group mygroup --version $APIVERSION --kind MyKind
 
 ```
 
-## Edit the Api files.
+## Edit the API files.
 
 ### Register your Types
 
-Add the following file to the pkg/apis directory
+Edit the following file to the pkg/apis directory to append their `AddToScheme` to your `AddToSchemes`:
 
 file: pkg/apis/mytype_addtoscheme.go
 ```
 package apis
 
 import (
-	mygroupv1alpha1 "github.com/username/myapirepo/apis/mygroup/v1alpha1"
+	mygroupv1alpha1 "github.com/myuser/myrepo/apis/mygroup/v1alpha1"
+	theirgroupv1alpha1 "github.com/theiruser/theirproject/apis/theirgroup/v1alpha1"
 )
 
 func init() {
 	// Register the types with the Scheme so the components can map objects 
 	// to GroupVersionKinds and back
-	AddToSchemes = append(AddToSchemes, mygroupv1alpha1.AddToScheme)
+	AddToSchemes = append(
+	  AddToSchemes, 
+	  mygroupv1alpha1.SchemeBuilder.AddToScheme,
+	  theirgroupv1alpha1.SchemeBuilder.AddToScheme,
+	)
 }
 
 ```
 
 ## Edit the Controller files
 
-### Use the correct import for your api
+### Use the correct imports for your API
 
 file: pkg/controllers/mytype_controller.go
 ```
-import mygroupv1alpha1 "github.com/example/myproject/apis/mygroup/v1alpha1"
+import (
+	mygroupv1alpha1 "github.com/myuser/myrepo/apis/mygroup/v1alpha1"
+	theirgroupv1alpha1 "github.com/theiruser/theirproject/apis/theirgroup/v1alpha1"
+)
+```
 
+### Update dependencies
+
+```
+dep ensure --add
 ```
 
 ## Prepare for testing
 
 #### Register your resource
 
-Add the registration code to the test framework
+Edit the `CRDDirectoryPaths` in your test suite by appending the path to their CRDs:
 
-file pkg/controller/my_agg_resource_controller_suite_test.go
+file pkg/controller/my_kind_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")},
+		CRDDirectoryPaths:  []string{
+		  filepath.Join("..", "..", "..", "config", "crds"),
+		  filepath.Join("..", "..", "..", "vendor", "github.com", "theiruser", "theirproject", "config", "crds"),
+        },
 		UseExistingCluster: true,
 	}
 
@@ -119,12 +134,6 @@ func TestMain(m *testing.M) {
 
 ```
 
-### Update dependencies
-
-```
-dep ensure --add
-```
-
 ## Helpful Tips
 
 ### Locate your domain and group variables