feat: support returning result in custom context key or environment

[tenstad]

Description of your changes

Related to https://crossplane.slack.com/archives/C08BBMDCH7W/p1769948003900819

Enables storing the fetched result in the environment (context) instead of the default context key used by this function. Makes it easy to load e.g. the data of a Secret or ConfigMap into environment (crossplane-contrib/function-environment-configs#78) and use it in patch and transform. Will also support loading namespace scoped EnvironmentConfigs into environment if such were to be created in the future.

To fetch a Secret into the environment:

        into:
          type: Environment
        extraResources:
          - kind: Secret
            apiVersion: v1
            namespace: default
            fromFieldPath: data
            type: Reference
            ref:
              name: credentials

Note: stacked on top of #84

See commit log for step by step implementation process.

Resolves crossplane-contrib/function-environment-configs#78

I have:

• Read and followed Crossplane's contribution process.
• Added or updated unit tests for my change.

[phisco]

This is a breaking change, we should keep into here and make it the default.

[phisco]

on top of that it's changing the semantic completely, previously each resource could go to a different key in the context, now they all go to the same one specified at the top level, but at different paths. I'd keep the into here, add a defaultInto at the top level which can be overridden from the resource level one, and make the top level one just a string, mentioning apiextensions.crossplane.io/environment as a well-known key in the comments for both.

[tenstad]

I don't quite understand, and think it might be the into.contextKey thats confusing. It is not the same as into within extraResources.

The top level into specifies where to put the results (what key to use in response.SetContextKey). It's a sort of toggle between the behaviour of function-extra-resources and function-environment-configs.

• type: Environment uses apiextensions.crossplane.io/environment
  (and also performs merge)
• type: Context defaults to apiextensions.crossplane.io/extra-resources
  (but can be changed using contextKey: apiextensions.custom.io/custom)

The following into configuration would be the same as not specifying into at all, and has the same behaviour as the function has today.

into:
  type: Context
  # rename contextKey to just `context`?
  contextKey: apiextensions.crossplane.io/extra-resources
extraResources:
  - kind: Namespace
    apiVersion: v1
    into: obj-0
    type: Reference
    ref:
      name: crossplane-system

[tenstad]

And yeah, we can ofc keep extraResources[].into instead of renaming the field to toFieldPath.

Should we then support the suggested nesting, or keep the current functionality using a simple key.

extraResources:
  - kind: Namespace
    fromFieldPath: metadata.name # only extract metadata.name
    into: resources.namespaces

Nested field path

apiextensions.crossplane.io/extra-resources:
  resources:
    namespaces: # nested inside of `resources`
      - kube-system
      - crossplane-system

Simple key

apiextensions.crossplane.io/extra-resources:
  resources.namespaces: # just a simple single-layer key
    - kube-system
    - crossplane-system

[tenstad]

The top level into might be a bad name, open to other suggestions.
It does two things, configures the context, and toggles between the behaviour of function-extra-resources and function-environment-configs.