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.

v0.3.0-beta.0

API Breaks

• #44: Add support for finding related resources via label selectors (by @xrstf) – see below for upgrade instructions

Features

• #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)

Misc

• #50: docs: add missing RBAC bindings / rules (by @dakraus)
• #48: Update to kcp 0.27.1 (by @xrstf)

---

Upgrade Notes

In order to upgrade to this release, you need to perform two important changes:

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

v0.2.0

Changelog since v0.1.0

• ✨ Add GoReleaser config and Release GitHub Action by @xmudrii in #36
• ✨ Add basic support for mutating object contents during syncing by @xrstf in #19
• ✨ Add end-to-end testing by @xrstf in #22
• ✨ Add workspace paths as annotations to synced objects by @xrstf in #15
• ✨ Label local objects with the agent name by @xrstf in #18
• ✨ Use OpenAPI schema to handle publishing non-CRD based resources by @xrstf in #29
• 🌱 Add first tests for the syncing logic by @xrstf in #28
• 🌱 Add integration tests for the apiexport controller by @xrstf in #24
• 🐛 Fix labels on related resources, fix syncing related resources, add first e2e test by @xrstf in #42
• 🐛 Handle long object names by @xrstf in #40
• 🐛 drop all non-selected versions from CRDs when creating APIResourceSchemas by @xrstf in #21
• 🐛 prefer CRDs when discovery API types, as CRDs contain more betterer information by @xrstf in #39
• 📖 (docs): fix the link by @buraksekili in #30
• 📖 update documentation by @xrstf in #14

v0.2.0-alpha.1

What's Changed

• 🐛 prefer CRDs when discovery API types, as CRDs contain more betterer information by @xrstf in #39

Full Changelog: v0.2.0-alpha.0...v0.2.0-alpha.1

v0.2.0-alpha.0

Changelog

• 5d43eb0 Merge pull request #29 from kcp-dev/openapi-crds
• 52642f9 Merge pull request #36 from xmudrii/release-action
• c4a8864 Add GoReleaser config file
• 6999810 add readme for the crd-puller
• bc88181 add test to publish a non-CRD resource
• 5c2657a make test name make more sense
• b65c07d go mod tidy
• e1fdd79 rewrite CRD discovery to use openapi instead
• d37eeae Add goreleaser-based release GitHub Action
• 525e44a Merge pull request #30 from buraksekili/patch-1
• 4542099 rename k8c to kcp
• e9222ec update discrepancy in the docs
• 256f3ac add a flag to create ns if not exists
• 6776a54 Update README.md
• cc43154 Merge pull request #28 from kcp-dev/sync-tests
• 50f7cd0 handle race condition when creating namespaces in the service cluster
• 73ad15e add test for the resource filtering
• 316bb1d actually implement support for resource filtering
• 3682cfb add first basic tests for basic object synchronization
• c513691 Merge pull request #24 from kcp-dev/more-e2e-tests
• 75dbdcf add the new tests
• 8513c2a add FAQ entry about typical bootstrapping errors in kcp
• 4936008 add --metrics-address and --health-address flags to disable metrics to prevent port conflicts in parallel tests
• a21dfe0 add new test for projection, fix ARS version projection
• ee9ac42 add new CronTab example CRDs
• 872c2fc found the first bug thanks to the e2e tests: the remaining version in the CRD must be served/stored
• b6f2abb add new tests for the apiresourceschema controller
• 242e2e6 Merge pull request #22 from kcp-dev/e2e-tests
• a1924a1 The linter 'tenv' is deprecated (since v1.64.0) due to: Duplicate feature another linter. Replaced by usetesting.
• eb01108 Go 1.24 compat, fix boilerplate checking
• a987006 actually test something useful
• 59b4fa2 loads of improvements, can now actually start the agent without it crashing immediately
• ffa9c0d add basic tester utils
• 0e24491 start kcp natively without kind, use envtest
• 5d3b31f download kcp via Makefile, do not mark tools as PHONY
• 1c3496e WIP
• 976d28c Merge pull request #21 from kcp-dev/drop-versions
• d93fec3 drop all non-selected versions from CRDs when creating APIResourceSchemas
• 0c4dc2a Merge pull request #19 from kcp-dev/re-enable-mutations
• 5d7e49e go mod tidy
• 4bef5f3 codegen
• 40aa688 update docs
• e29acd5 bring back support for mutations, remove Rudi support
• 491adf3 Merge pull request #18 from kcp-dev/label-agent-name
• d3934fb update docs
• 78bebb4 label local objects with the agent name so that multiple agents can serve the same API
• 997725a Merge pull request #15 from kcp-dev/add-cluster-paths
• 4b4d9d7 s/clusterPath/workspacePath/g due to popular demand
• 778b49e update tests
• ea71042 use annotation because labels do not allow colons
• 9736d94 use typed variables for name/paths, ensure the path is handed through the callstack
• 511599c load and store cluster path in sync context
• dca5fbe ad new enableClusterPaths field to PublishedResources
• 9edf625 Merge pull request #14 from kcp-dev/update-docs
• 0398d04 update helm usage
• 009fcef update documentation

v0.1.0

Initial release.