Merge pull request #60 from kcp-dev/sdk-module

Introduce standalone SDK

Author: kcp-ci-bot

Makefile

@@ -62,16 +62,18 @@ $(GIMPS):
 	  gimps \
 	  ${GIMPS_VERSION}
 
+# wwhrd is installed as a Go module rather than from the provided
+# binaries because there is no arm64 binary available from the author.
+
 WWHRD = _tools/wwhrd
-WWHRD_VERSION = 0.4.0
+WWHRD_VERSION = 06b99400ca6db678386ba5dc39bbbdcdadb664ff
 
 .PHONY: $(WWHRD)
 $(WWHRD):
-	@hack/download-tool.sh \
-	  https://github.com/frapposelli/wwhrd/releases/download/v${WWHRD_VERSION}/wwhrd_${WWHRD_VERSION}_${GOOS}_${GOARCH}.tar.gz \
+	@GO_MODULE=true hack/download-tool.sh \
+	  github.com/frapposelli/wwhrd \
 	  wwhrd \
-	  ${WWHRD_VERSION} \
-	  wwhrd
+	  ${WWHRD_VERSION}
 
 BOILERPLATE = _tools/boilerplate
 BOILERPLATE_VERSION = 0.3.0

README.md

@@ -5,6 +5,21 @@
 [![GitHub release (latest SemVer)](https://img.shields.io/github/v/release/kcp-dev/api-syncagent?sort=semver)](https://img.shields.io/github/v/release/kcp-dev/api-syncagent?sort=semver)
 [![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Fkcp-dev%2Fapi-syncagent.svg?type=shield)](https://app.fossa.com/projects/git%2Bgithub.com%2Fkcp-dev%2Fapi-syncagent?ref=badge_shield)
 
+The kcp API Sync Agent is a Kubernetes controller capable of synchronizing objects from many kcp
+workspaces onto a single Kubernetes cluster (with kcp being the source of truth). In doing so it will
+move the desired state (usually the spec) of an object from kcp to the local cluster where the agent
+is running, and move the current object status back up into kcp. The agent can also sync so-called
+related objects, like a Secret belonging to a Certificate, in both directions.
+
+The agent can be used to provide an API in kcp and then serving it from a remote Kubernetes cluster
+where the actual workload is then processed, usually by a 3rd-party operator. In many situations the
+synchronized objects are further processed using tools like Crossplane.
+
+## Documentation
+
+Please visit [https://docs.kcp.io/api-syncagent](https://docs.kcp.io/api-syncagent) for the latest
+documentation.
+
 ## Troubleshooting
 
 If you encounter problems, please [file an issue][1].

docs/content/releasing.md

@@ -0,0 +1,29 @@
+# Release Process
+
+The guide describes how to release a new version of the api-syncagent.
+
+## Prerequisites
+
+1. Have all desired changes merged and/or cherrypicked into the appropriate
+   release branch.
+
+## Minor Release
+
+Minor releases (0.x) are tagged directly on the `main` branch and the `v0.X.0`
+tag represents where the corresponding `release/v0.X` branch branches off.
+
+1. Checkout the desired `main` branch commit.
+1. Tag the main module: `git tag -m "version 0.X" v0.X.0`
+1. Tag the SDK module: `git tag -m "SDK version 0.X" sdk/v0.X.0`
+1. Push the tags: `git push upstream v0.X.0 sdk/v0.X.0`
+1. Create the release branch: `git checkout -B release/v0.X`
+1. Push the release branch: `git push -u upstream release/v0.X`
+
+## Patch Releases
+
+Patch releases (v0.x.y) are tagged with in a release branch.
+
+1. Checkout the desired `release/v0.X` branch commit.
+1. Tag the main module: `git tag -m "version 0.X.Y" v0.X.Y`
+1. Tag the SDK module: `git tag -m "SDK version 0.X.Y" sdk/v0.X.Y`
+1. Push the tags: `git push upstream v0.X.Y sdk/v0.X.Y`

docs/mkdocs.yml

@@ -25,6 +25,7 @@ nav:
   - Publishing Resources: publish-resources.md
   - Consuming Services: consuming-services.md
   - FAQ: faq.md
+  - Release Process: releasing.md
 
 # Site content
 docs_dir: 'content'

go.mod

@@ -2,7 +2,7 @@ module github.com/kcp-dev/api-syncagent
 
 go 1.23.0
 
-toolchain go1.24.0
+replace github.com/kcp-dev/api-syncagent/sdk => ./sdk
 
 replace (
 	k8s.io/apiextensions-apiserver => github.com/kcp-dev/kubernetes/staging/src/k8s.io/apiextensions-apiserver v0.0.0-20250313100806-0011b8c72acd
@@ -17,8 +17,7 @@ require (
 	github.com/go-logr/logr v1.4.2
 	github.com/go-logr/zapr v1.3.0
 	github.com/google/go-cmp v0.7.0
-	github.com/kcp-dev/apimachinery/v2 v2.0.1-0.20250223115924-431177b024f3
-	github.com/kcp-dev/client-go v0.0.0-20250223133118-3dea338dc267
+	github.com/kcp-dev/api-syncagent/sdk v0.0.0-00010101000000-000000000000
 	github.com/kcp-dev/code-generator/v2 v2.3.1
 	github.com/kcp-dev/kcp v0.27.1
 	github.com/kcp-dev/kcp/sdk v0.27.1
@@ -40,7 +39,6 @@ require (
 	k8s.io/utils v0.0.0-20240711033017-18e509b52bc8
 	sigs.k8s.io/controller-runtime v0.18.3
 	sigs.k8s.io/controller-tools v0.16.5
-	sigs.k8s.io/structured-merge-diff/v4 v4.6.0
 	sigs.k8s.io/yaml v1.4.0
 )
 
@@ -61,7 +59,6 @@ require (
 	github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc // indirect
 	github.com/distribution/reference v0.6.0 // indirect
 	github.com/emicklei/go-restful/v3 v3.12.2 // indirect
-	github.com/evanphx/json-patch v5.9.11+incompatible // indirect
 	github.com/fatih/color v1.18.0 // indirect
 	github.com/felixge/httpsnoop v1.0.4 // indirect
 	github.com/fsnotify/fsnotify v1.8.0 // indirect
@@ -87,6 +84,8 @@ require (
 	github.com/inconshreveable/mousetrap v1.1.0 // indirect
 	github.com/josharian/intern v1.0.0 // indirect
 	github.com/json-iterator/go v1.1.12 // indirect
+	github.com/kcp-dev/apimachinery/v2 v2.0.1-0.20250223115924-431177b024f3 // indirect
+	github.com/kcp-dev/client-go v0.0.0-20250223133118-3dea338dc267 // indirect
 	github.com/klauspost/compress v1.17.11 // indirect
 	github.com/kylelemons/godebug v1.1.0 // indirect
 	github.com/mailru/easyjson v0.9.0 // indirect
@@ -158,4 +157,5 @@ require (
 	k8s.io/kubernetes v1.31.6 // indirect
 	sigs.k8s.io/apiserver-network-proxy/konnectivity-client v0.30.3 // indirect
 	sigs.k8s.io/json v0.0.0-20241014173422-cfa47c3a1cc8 // indirect
+	sigs.k8s.io/structured-merge-diff/v4 v4.6.0 // indirect
 )

hack/boilerplate/generated/boilerplate.go.txt

@@ -0,0 +1,15 @@
+/*
+Copyright The KCP Authors.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/

hack/reconciling.yaml

@@ -16,7 +16,7 @@
 # https://github.com/kubermatic/reconciler
 
 package: reconciling
-boilerplate: hack/boilerplate/boilerplate.go.txt
+boilerplate: hack/boilerplate/generated/boilerplate.go.txt
 resourceTypes:
   # kcp-dev/v1alpha1
   - { package: github.com/kcp-dev/kcp/sdk/apis/apis/v1alpha1, importAlias: kcpdevv1alpha1, resourceName: APIExport }

hack/update-codegen-crds.sh

@@ -19,17 +19,16 @@ set -euo pipefail
 cd $(dirname $0)/..
 source hack/lib.sh
 
-sed="sed"
-[ "$(command -v gsed)" ] && sed="gsed"
+mkdir -p _tools
+export GOBIN=$(realpath _tools)
+
+go install k8c.io/reconciler/cmd/reconciler-gen
+go install sigs.k8s.io/controller-tools/cmd/controller-gen
 
 echodate "Generating reconciling helpers…"
 
 reconcileHelpers=internal/resources/reconciling/zz_generated_reconcile.go
-go run k8c.io/reconciler/cmd/reconciler-gen --config hack/reconciling.yaml > $reconcileHelpers
-
-currentYear=$(date +%Y)
-$sed -i "s/Copyright YEAR/Copyright $currentYear/g" $reconcileHelpers
-$sed -i "s/Copyright © YEAR/Copyright © $currentYear/g" $reconcileHelpers
+$GOBIN/reconciler-gen --config hack/reconciling.yaml > $reconcileHelpers
 
 CRD_DIR=deploy/crd
 KCP_CRD_DIR="$CRD_DIR/kcp.io"
@@ -38,17 +37,14 @@ mkdir -p "$KCP_CRD_DIR"
 
 echodate "Generating openAPI v3 CRDs…"
 
-# this also generates the deepcopy funcs
-go run sigs.k8s.io/controller-tools/cmd/controller-gen \
+$GOBIN/controller-gen \
   crd \
-  object:headerFile=./hack/boilerplate/boilerplate.go.txt \
   paths=./sdk/apis/... \
   output:crd:dir=./$KCP_CRD_DIR
 
 # these are types only used for testing the syncer
-go run sigs.k8s.io/controller-tools/cmd/controller-gen \
+$GOBIN/controller-gen \
   crd \
-  object:headerFile=./hack/boilerplate/boilerplate.go.txt \
   paths=./internal/sync/apis/... \
   output:crd:dir=./internal/sync/crd/
 

hack/update-codegen-sdk.sh

@@ -19,43 +19,55 @@ set -euo pipefail
 cd $(dirname $0)/..
 source hack/lib.sh
 
-BOILERPLATE_HEADER="$(realpath hack/boilerplate/boilerplate.go.txt)"
+BOILERPLATE_HEADER="$(realpath hack/boilerplate/generated/boilerplate.go.txt)"
+SDK_MODULE="github.com/kcp-dev/api-syncagent/sdk"
+APIS_PKG="$SDK_MODULE/apis"
 
-BASE=github.com/kcp-dev/api-syncagent
-MODULE="$BASE/sdk"
-SDK_DIR=sdk
-SDK_PKG="$MODULE"
-APIS_PKG="$MODULE/apis"
+mkdir -p _tools
+export GOBIN=$(realpath _tools)
 
 set -x
-rm -rf -- $SDK_DIR/{applyconfiguration,clientset,informers,listers}
 
-go run k8s.io/code-generator/cmd/applyconfiguration-gen \
+go install k8s.io/code-generator/cmd/applyconfiguration-gen
+go install k8s.io/code-generator/cmd/client-gen
+go install github.com/kcp-dev/code-generator/v2
+go install github.com/openshift-eng/openshift-goimports
+go install sigs.k8s.io/controller-tools/cmd/controller-gen
+
+# these are types only used for testing the syncer
+$GOBIN/controller-gen \
+  "object:headerFile=$BOILERPLATE_HEADER" \
+  paths=./internal/sync/apis/...
+
+cd sdk
+rm -rf -- applyconfiguration clientset informers listers
+
+$GOBIN/controller-gen \
+  "object:headerFile=$BOILERPLATE_HEADER" \
+  paths=./apis/...
+
+$GOBIN/applyconfiguration-gen \
   --go-header-file "$BOILERPLATE_HEADER" \
-  --output-dir $SDK_DIR/applyconfiguration \
-  --output-pkg $SDK_PKG/applyconfiguration \
-  $APIS_PKG/syncagent/v1alpha1
+  --output-dir applyconfiguration \
+  --output-pkg $SDK_MODULE/applyconfiguration \
+  ./apis/...
 
-go run k8s.io/code-generator/cmd/client-gen \
-  --input-base "" \
-  --input $APIS_PKG/syncagent/v1alpha1 \
-  --clientset-name versioned \
+$GOBIN/client-gen \
   --go-header-file "$BOILERPLATE_HEADER" \
-  --output-dir $SDK_DIR/clientset \
-  --output-pkg $SDK_PKG/clientset
+  --output-dir clientset \
+  --output-pkg $SDK_MODULE/clientset \
+  --clientset-name versioned \
+  --input-base $APIS_PKG \
+  --input syncagent/v1alpha1
 
-go run github.com/kcp-dev/code-generator/v2 \
-  "client:headerFile=$BOILERPLATE_HEADER,apiPackagePath=$APIS_PKG,outputPackagePath=$SDK_PKG,singleClusterClientPackagePath=$SDK_PKG/clientset/versioned,singleClusterApplyConfigurationsPackagePath=$SDK_PKG/applyconfiguration" \
-  "informer:headerFile=$BOILERPLATE_HEADER,apiPackagePath=$APIS_PKG,outputPackagePath=$SDK_PKG,singleClusterClientPackagePath=$SDK_PKG/clientset/versioned" \
+$GOBIN/code-generator \
+  "client:headerFile=$BOILERPLATE_HEADER,apiPackagePath=$APIS_PKG,outputPackagePath=$SDK_MODULE,singleClusterClientPackagePath=$SDK_MODULE/clientset/versioned,singleClusterApplyConfigurationsPackagePath=applyconfiguration" \
+  "informer:headerFile=$BOILERPLATE_HEADER,apiPackagePath=$APIS_PKG,outputPackagePath=$SDK_MODULE,singleClusterClientPackagePath=$SDK_MODULE/clientset/versioned" \
   "lister:headerFile=$BOILERPLATE_HEADER,apiPackagePath=$APIS_PKG" \
-  "paths=./sdk/apis/..." \
-  "output:dir=$SDK_DIR"
+  "paths=./apis/..." \
+  "output:dir=."
 
 # Use openshift's import fixer because gimps fails to parse some of the files;
 # its output is identical to how gimps would sort the imports, but it also fixes
 # the misplaced go:build directives.
-for submodule in "applyconfiguration" "clientset" "informers" "listers"; do
-  go run github.com/openshift-eng/openshift-goimports \
-    --module "$MODULE/$submodule" \
-    --path "$SDK_DIR/$submodule"
-done
+$GOBIN/openshift-goimports .

hack/verify-boilerplate.sh

@@ -22,11 +22,22 @@ source hack/lib.sh
 make --no-print-directory _tools/boilerplate
 
 echo "Checking file boilerplates…"
+
+set -x
+
 _tools/boilerplate \
   -boilerplates hack/boilerplate \
   -exclude .github \
   -exclude internal/certificates/triple \
+  -exclude sdk/applyconfiguration \
   -exclude sdk/clientset \
   -exclude sdk/informers \
   -exclude sdk/listers \
   -exclude test/crds
+
+_tools/boilerplate \
+  -boilerplates hack/boilerplate/generated \
+  sdk/applyconfiguration \
+  sdk/clientset \
+  sdk/informers \
+  sdk/listers