Kong / Kong/kongctl

Bug: `!ref` YAML tag is not broadly supported

Open
#156 3 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

bug medium-priority triaged
Dominant language
Go
Stars
17
Forks
24
Avg merge
8h 13m
Merged PRs (30d)
196

Description

## Summary
Applying declarative configs that use `!ref` placeholders on portal fields (e.g., one portal’s `description` referencing another portal’s `display_name`) leaves the placeholders unresolved in Konnect and fails to surface
circular dependencies.

## Observed Behaviour
- `kongctl apply ...` with two portals referencing each other succeeds.
- `kongctl get portals` shows descriptions still set to `__REF__:portal-cycle-b#display_name` (strings are neither resolved nor rejected).
- No circular-dependency error is raised even though the references form a loop.

## Analysis
- `!ref` tags expand to `__REF__:...` placeholders that the declarative loader/planner should resolve before contacting Konnect.
- Portal fields come from the embedded `kkComps.CreatePortal` struct; the current reference resolver only inspects the top-level wrapper fields and stops when the field isn’t found.
- Because the resolver never traverses the embedded struct, it leaves the placeholder untouched and the circular-reference guard never activates (the resolution path is never recorded).

## Proposed Fix
1. Update the resolver helpers (loader and planner) to descend into anonymous/inline structs and pointers so fields embedded from SDK types are discoverable.
2. While there, record the resolution key in the `resolutionPath` stack so genuine cycles report an explicit circular reference.
3. Add unit coverage proving that portal references resolve correctly and that cycles now trigger the guard.
4. Once fixed, re-enable the paused e2e step to validate the behaviour end-to-end.

## Testing
- New resolver unit tests for embedded-field lookups and circular-detection.
- Rerun the declarative error scenario (with the circular step re-enabled) against Konnect to ensure the fix produces the expected error.

```
_defaults:
kongctl:
namespace: declarative-errors

portals:
- ref: portal-cycle-a
name: portal-cycle-a
description: !ref portal-cycle-b#display_name
display_name: "Portal Cycle A"

- ref: portal-cycle-b
name: portal-cycle-b
description: !ref portal-cycle-a#display_name
display_name: "Portal Cycle B"
```

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the resolver helpers in the loader and planner, focusing on how embedded or anonymous fields and pointers from kkComps.CreatePortal are inspected. Run the resolver unit tests and the declarative error scenario; done means portal references resolve, circular references raise the guard, and the paused e2e step passes when re-enabled.

Written by the indexing model from the issue text.

Assessment

Tech stack
go
Domain
cli
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.