The team is happy to announce the 3rd minor release of the kcp Sync Agent. This release comes with a whole number of significant improvements, but also some lighter API breaks. Please read the notes below carefully before upgrading.
Changelog since version 0.2
API Breaks
- The default naming rules in PublishedResources have changed to now use SHA-3 instead of SHA-1.
- The configuration for related resources has been adjusted to allow for label selectors and more.
New Features
- #44: Add support for finding related resources via label selectors (by @xrstf) – see below for upgrade instructions
- #44: Add support for having one related resource match many objects (by @xrstf)
- #52: The sync-agent does not mistakenly assume that 1 APIExport contains exactly 1 API group, and instead now correctly allows to have as many API groups as desired in one APIExport. You still need 1 agent per APIExport though (by @xrstf)
- #52: Added
group
to the projection settings in a PublishedResource, allowing to rewrite the API group (by @xrstf) - #66: Support Go template expresssions in PublishedResources (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)
- #77: Add
--disabled-controllers
to turn off one or more of theapiresourceschema
,apiexport
and/orsync
controllers (by @xrstf) - #76: Replace
crd-puller
with a more powerfulpubres-toolkit
(by @xrstf)
Misc
Deprecations
$variables
in naming rules are deprecated now and replaced with 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
Updating related resources
You need to manually update every PublishedResource
that contains related resources.
This was the old structure:
spec:
related:
- id: credentials
reference:
name:
path: metadata.name
regex: {pattern: ..., replacement: ...}
# optional namespace
namespace:
path: metadata.foobar
regex: {pattern: ..., replacement: ...}
This is the new structure (omitting the new fields introduced in 0.3):
spec:
related:
- id: credentials
object:
reference:
path: metadata.name
regex: {pattern: ..., replacement: ...}
# optional namespace
namespace:
reference:
path: metadata.foobar
regex: {pattern: ..., replacement: ...}
Re-adjust projection rules
Since the api-syncagent now does not automatically project (= rename) the API group of published CRDs, if you want to keep the old behaviour (where every CRD, regardless of its API group, gets renamed to the group defined by the APIExport's name), you need to explicitly configure a projection.
In your PublishedResources, add
spec:
projection:
group: the.group.to.project.to # most like this is your APIExport's name if you want to keep the old behaviour
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.