Changelog
API Breaks
- The default naming rules in PublishedResources have changed to now use SHA-3 instead of SHA-1. See below for upgrade instructions.
New Features
- #66: Support Go template expresssions in PublishedResources, deprecate object references (by @xrstf)
- #62: Handle CRD updates on the service cluster and create new APIResourceSchemas in kcp; allow to publish more than one version of a CRD (by @xrstf)
- #60:
github.com/kcp-dev/api-syncagent/sdk
is now a standalone Go module (by @xrstf) - #53, #54, #55, #57: Significantly improve documentation (by @mirzakopic)
Deprecations
$variables
in naming rules are deprecated now and replaced with Go templates.- References (JSONPaths) have been deprecated in favor of Go templates.
- Publishing just a single version of a CRD is deprecated, instead admins should configure a list of versions (which often just contains one).
Updates
- #67: Update to Go 1.24.3 (by @xrstf)
- #64: Update golangci-lint to 2.1.6 (by @xrstf)
- #65: Reorganise docs for a better reading experience (by @embik)
Upgrade Notes
Naming based on $variables
is deprecated
Originally the agent supported a very limited set of custom placeholder that could be used to configuring naming rules. Since this was extremely limited, with beta.1 we decided to deprecate that syntax and replace it with Go templates, since templates are also now used in more places throughout a PublishedResource.
Please refer to the documentation for more details on the available objects and functions.
Naming Rules use SHA-3 now
Previously, the default rules for naming objects in a PublishedResource were
naming:
namespace: "$remoteClusterName"
name: "$remoteNamespaceHash-$remoteNameHash"
Since $variable
support is deprecated, this release takes the opportunity to forgoe the old implicit hashing (for the $...Hash
variables) and instead recommend explicit hashing.
The new defaults are
naming:
namespace: "{{ .ClusterName }}"
name: "{{ .Object.metadata.namespace | sha3short }}-{{ .Object.metadata.name | sha3short }}"
-
If you had not configured explicit naming rules, these new defaults would cause new objects to be created in new locations. This might be undesirable (existing objects are still linked via labels and so should continue to work). To keep the old naming scheme, override the
naming
section and use theshortHash
function, which only exists for backwards compatibility.naming: namespace: "{{ .ClusterName }}" name: "{{ .Object.metadata.namespace | shortHash }}-{{ .Object.metadata.name | shortHash }}"
-
If you already had custom
naming
rules, you are encouraged to transform them into Go templates since the$variable
syntax is deprecated. Please refer to the documentation for more details on the available objects and functions.
CRDs can publish multiple versions
When publishing a CRD using a PublishedResource, you can now publish more than just one version. To allow this, the old version
field in a PublishedResource has been deprecated and replaced with a versions
field:
spec:
resource:
kind: Certificate
apiGroup: cert-manager.io
versions: [v1] # was previously `version: v1`
The same applies to projections, where now instead of a single new version, a map of old version to new version is configured:
spec:
projection:
versions:
# old version => new version;
# this must not map multiple versions to the same new version.
v1: v1beta1
Note that even though the agent can now publish more than one version, there is currently no support whatsoever for converting between versions within kcp. For that reason you probably want to continue publishing a single version only.
References are deprecated
A reference is basically a simplified JSONPath expression, like .spec.secretName
. Since the new Go template support makes the entire Kubernetes objects available as unstructured objects, a reference like the previous one can now be written as {{ .Object.spec.secretName }}
.
Since Go templates can do everything and more than references could, references have been generally deprecated.