v0.3.0-beta.1

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 the shortHash 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.