Skip to content

Editing APIs

Tips, tutorials, examples, best practices.

Tips

Some helpful tips to make life easier while writing conversion routines.

  • Do not delete fields. It's easier to write loss-less conversion routines if the field is renamed to something that indicates it's no longer used. This becomes more important in the spoke-hub-spoke scenario, because the hub will not have an annotation preserving the original spoke's values.
  • The +kubebuilder validation directives in the CRD comments count as code. Adding, deleting, or modifying these directives will require that the API version be bumped.

Example 1: Add a field to a resource

In the DWS repository, add a new field to the Status section of the SystemConfiguration hub resource. In this case, the hub version is v1alpha2.

Step 1: Add a new ResourceError field

diff --git a/api/v1alpha2/systemconfiguration_types.go b/api/v1alpha2/systemconfiguration_types.go
index 3e4d29fb..2c65e3a0 100644
--- a/api/v1alpha2/systemconfiguration_types.go
+++ b/api/v1alpha2/systemconfiguration_types.go
@@ -82,6 +82,9 @@ type SystemConfigurationSpec struct {
 type SystemConfigurationStatus struct {
        // Ready indicates when the SystemConfiguration has been reconciled
        Ready bool `json:"ready"`
+
+       // Error information
+       ResourceError `json:",inline"`
 }

 //+kubebuilder:object:root=true

(An aside: That ResourceError type used for this new field is inlined, bringing a field named Error, so that's what we'll see next in the conversion routines.)

Step 2: Run the conversion code generator

Run the generator to update the generated conversion routines for this type.

make generate-go-conversions

This will emit some scary-looking output:

/Users/droehrich/work/rabsw/dws-7.git/bin/conversion-gen \
        --output-file=zz_generated.conversion.go \
        --go-header-file=./hack/boilerplate.go.txt \
        ./api/v1alpha1
E0913 11:13:26.993464   23295 conversion.go:741] Warning: could not find nor generate a final Conversion function for github.com/DataWorkflowServices/dws/api/v1alpha2.SystemConfigurationStatus -> github.com/DataWorkflowServices/dws/api/v1alpha1.SystemConfigurationStatus
E0913 11:13:26.993609   23295 conversion.go:742]   the following fields need manual conversion:
E0913 11:13:26.993613   23295 conversion.go:744]       - ResourceError

Let's look around for a missing routine:

$ git status
On branch api-change-demo
Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
    modified:   api/v1alpha1/zz_generated.conversion.go
    modified:   api/v1alpha2/systemconfiguration_types.go

Look at the generated code for a clue. There are two here. First, a comment about our new field requiring manual conversion. Second, the generated entrypoint for the SystemConfigurationStatus conversion routine has been taken away:

$ git diff -U1 api/v1alpha1/zz_generated.conversion.go 
diff --git a/api/v1alpha1/zz_generated.conversion.go b/api/v1alpha1/zz_generated.conversion.go
index 1f1b3cb6..d7c915aa 100644
--- a/api/v1alpha1/zz_generated.conversion.go
+++ b/api/v1alpha1/zz_generated.conversion.go
@@ -2082,2 +2082,3 @@ func autoConvert_v1alpha2_SystemConfigurationStatus_To_v1alpha1_SystemConfigurat
        out.Ready = in.Ready
+       // WARNING: in.ResourceError requires manual conversion: does not exist in peer-type
        return nil
@@ -2085,7 +2086,2 @@ func autoConvert_v1alpha2_SystemConfigurationStatus_To_v1alpha1_SystemConfigurat

-// Convert_v1alpha2_SystemConfigurationStatus_To_v1alpha1_SystemConfigurationStatus is an autogenerated conversion function.
-func Convert_v1alpha2_SystemConfigurationStatus_To_v1alpha1_SystemConfigurationStatus(in *v1alpha2.SystemConfigurationStatus, out *SystemConfigurationStatus, s conversion.Scope) error {
-       return autoConvert_v1alpha2_SystemConfigurationStatus_To_v1alpha1_SystemConfigurationStatus(in, out, s)
-}
-
 func autoConvert_v1alpha1_SystemConfigurationStorageNode_To_v1alpha2_SystemConfigurationStorageNode(in *SystemConfigurationStorageNode, out *v1alpha2.SystemConfigurationStorageNode, s conversion.Scope) error {

The generator is forcing us to acknowledge that we have conversion covered for that new field. We have to manually replace that entrypoint to hook up the conversion again.

Step 3: Restore the generated conversion entrypoint

At the end of api/v1alpha1/conversion.go we will find other entrypoint routines like this one, for earlier changes to the SystemConfiguration type. Cut-n-paste that entrypoint routine from the diff above into an appropriate place near the end of conversion.go, adjusting it just enough so make vet succeeds.

$ git diff -U1 api/v1alpha1/conversion.go
diff --git a/api/v1alpha1/conversion.go b/api/v1alpha1/conversion.go
index f409f9b2..e11a41eb 100644
--- a/api/v1alpha1/conversion.go
+++ b/api/v1alpha1/conversion.go
@@ -581,2 +581,6 @@ func Convert_v1alpha2_SystemConfigurationSpec_To_v1alpha1_SystemConfigurationSpe

+func Convert_v1alpha2_SystemConfigurationStatus_To_v1alpha1_SystemConfigurationStatus(in *dwsv1alpha2.SystemConfigurationStatus, out *SystemConfigurationStatus, s apiconversion.Scope) error {
+       return autoConvert_v1alpha2_SystemConfigurationStatus_To_v1alpha1_SystemConfigurationStatus(in, out, s)
+}
+
 func Convert_v1alpha2_StorageSpec_To_v1alpha1_StorageSpec(in *dwsv1alpha2.StorageSpec, out *StorageSpec, s apiconversion.Scope) error {

Confirm that it compiles:

make vet

Step 4: Add the new field to the conversion routine

Add this field to the ConvertTo() (convert from spoke to hub) conversion routine for the SystemConfiguration type.

$ git diff -U1 api/v1alpha1/conversion.go
diff --git a/api/v1alpha1/conversion.go b/api/v1alpha1/conversion.go
index f409f9b2..706f16bb 100644
--- a/api/v1alpha1/conversion.go
+++ b/api/v1alpha1/conversion.go
@@ -369,2 +369,3 @@ func (src *SystemConfiguration) ConvertTo(dstRaw conversion.Hub) error {
                dst.Spec.PortsCooldownInSeconds = restored.Spec.PortsCooldownInSeconds
+               dst.Status.Error = restored.Status.Error

In this case, we won't add this field to the ConvertFrom() (convert from hub to spoke) routine because we don't need to represent it in any way in the spoke. This will not always be the case, so do what makes sense for your particular change.

Try the test suite, but make it easy on yourself and try make vet first:

make vet
make test