Skip to content

v0.3.0

Latest
Compare
Choose a tag to compare
@github-actions github-actions released this 24 Jun 13:22
· 6 commits to main since this release
v0.3.0
c083316

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 the apiresourceschema, apiexport and/or sync controllers (by @xrstf)
  • #76: Replace crd-puller with a more powerful pubres-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 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.