Object file parameter (#3487)

* feat: support @ prefix for object parameters from files

Enable users to load object-type parameters from JSON files using
the @ prefix syntax, similar to curl and kubectl. This provides a
convenient way to pass complex configuration objects without inline
JSON strings.

Usage:
  porter install --param config=@/path/to/config.json
  porter install --param config='{"key": "value"}'

Parameter sets also support @ prefix:
  parameters:
    - name: config
      source:
        value: @/path/to/config.json

Security considerations:
- Only applies to user-provided values (CLI flags/parameter sets)
- Does NOT work with default values in bundle definitions
- Validates JSON structure before processing
- Clear error messages for missing files or invalid JSON

Changes:
- Add @ prefix detection in getUnconvertedValueFromRaw()
- Read and validate JSON file contents for object parameters
- Add comprehensive unit tests covering success/error cases
- Add test fixtures for valid/invalid JSON scenarios

Signed-off-by: Kim Christensen <[email protected]>

* test: add integration tests for object parameter files

Add comprehensive integration tests for object-type parameters
loaded from files using the @ prefix syntax. Tests cover:
- CLI parameter with @ prefix reading from file
- Inline JSON parameter without @ prefix
- Parameter set with @ prefix
- Error handling for missing files
- Error handling for invalid JSON files

Also adds test bundle that uses template syntax to access
object parameter fields in bundle execution steps.

Signed-off-by: Kim <[email protected]>
Signed-off-by: Kim Christensen <[email protected]>

* docs: add documentation for @ prefix file loading

Update CLI help text and user documentation to describe the
@ prefix syntax for loading object parameters from JSON files.

Changes include:
- Updated --param flag help text with @ prefix example
- Added @ prefix examples to install/upgrade/invoke commands
- Added "Object Parameters from Files" section to intro docs
- Updated quickstart guide with @ prefix usage
- Enhanced parameter set file format documentation
- Added example of @ prefix in parameter set YAML

The documentation emphasizes the security constraint that
@ prefix only works for user-provided values, not defaults.

Signed-off-by: Kim <[email protected]>
Signed-off-by: Kim Christensen <[email protected]>

* docs: Update generated documentation files

Signed-off-by: Kim Christensen <[email protected]>

* docs: use path source in parameter sets for file loading

Update documentation to describe the proper `path` source syntax
for parameter set definitions instead of the `@` prefix.

Changes:
- Clarify that `@` prefix is only for CLI --param flags
- Add comprehensive examples showing `path` source in both YAML
  and JSON format for parameter set definitions
- Update parameter set example to use schemaVersion 1.1.0
- Remove incorrect documentation about `@` prefix in value sources
- Distinguish between CLI usage (@Prefix) and parameter set usage
  (path source)

The `path` source is the correct way to reference files in parameter
set definitions, while the `@` prefix remains a convenient shortcut
for command-line parameter overrides.

Signed-off-by: Kim Christensen <[email protected]>

* ci: add object_param_test to integration test workflows

Signed-off-by: Kim Christensen <[email protected]>

---------

Signed-off-by: Kim Christensen <[email protected]>
Signed-off-by: Kim <[email protected]>

Author: kichristensen

.github/workflows/porter-integration-pr.yml

@@ -81,6 +81,11 @@ jobs:
     uses: getporter/porter/.github/workflows/integ-reuseable-workflow.yml@main
     with:
       test_name: outputs_test
+  object_param_integration_test:
+    name: Object Param Integration Test
+    uses: getporter/porter/.github/workflows/integ-reuseable-workflow.yml@main
+    with:
+      test_name: object_param_test
   publish_integration_test:
     name: Publish Integration Test
     uses: getporter/porter/.github/workflows/integ-reuseable-workflow.yml@main

.github/workflows/porter-integration-release.yml

@@ -92,6 +92,12 @@ jobs:
     with:
       test_name: outputs_test
       registry: ${{inputs.registry}}
+  object_param_integration_test:
+    name: Object Param Integration Test
+    uses: getporter/porter/.github/workflows/integ-reuseable-workflow.yml@main
+    with:
+      test_name: object_param_test
+      registry: ${{inputs.registry}}
   publish_integration_test:
     name: Publish Integration Test
     uses: getporter/porter/.github/workflows/integ-reuseable-workflow.yml@main

cmd/porter/installations.go

@@ -237,6 +237,7 @@ The docker driver runs the bundle container using the local Docker host. To use
   porter installation install --reference localhost:5000/ghcr.io/getporter/examples/kubernetes:v0.2.0 --insecure-registry --force
   porter installation install MyAppInDev --file myapp/bundle.json
   porter installation install --parameter-set azure --param test-mode=true --param header-color=blue
+  porter installation install --param [email protected]
   porter installation install --credential-set azure --credential-set kubernetes
   porter installation install --driver debug
   porter installation install --label env=dev --label owner=myuser
@@ -287,6 +288,7 @@ The docker driver runs the bundle container using the local Docker host. To use
   porter installation upgrade --reference localhost:5000/ghcr.io/getporter/examples/kubernetes:v0.2.0 --insecure-registry --force
   porter installation upgrade MyAppInDev --file myapp/bundle.json
   porter installation upgrade --parameter-set azure --param test-mode=true --param header-color=blue
+  porter installation upgrade --param [email protected]
   porter installation upgrade --credential-set azure --credential-set kubernetes
   porter installation upgrade --driver debug
 `,
@@ -337,6 +339,7 @@ The docker driver runs the bundle container using the local Docker host. To use
   porter installation invoke --reference localhost:5000/ghcr.io/getporter/examples/kubernetes:v0.2.0 --insecure-registry --force
   porter installation invoke --action ACTION MyAppInDev --file myapp/bundle.json
   porter installation invoke --action ACTION  --parameter-set azure --param test-mode=true --param header-color=blue
+  porter installation invoke --action ACTION --param [email protected]
   porter installation invoke --action ACTION --credential-set azure --credential-set kubernetes
   porter installation invoke --action ACTION --driver debug
 `,
@@ -427,7 +430,7 @@ func addBundleActionFlags(f *pflag.FlagSet, actionOpts porter.BundleAction) {
 	f.StringArrayVarP(&opts.ParameterSets, "parameter-set", "p", nil,
 		"Parameter sets to use when running the bundle. It should be a named set of parameters and may be specified multiple times.")
 	f.StringArrayVar(&opts.Params, "param", nil,
-		"Define an individual parameter in the form NAME=VALUE. Overrides parameters otherwise set via --parameter-set. May be specified multiple times.")
+		"Define an individual parameter in the form NAME=VALUE. Overrides parameters otherwise set via --parameter-set. May be specified multiple times. For object parameters, use @FILEPATH to load JSON from a file (e.g., --param [email protected]).")
 	f.StringArrayVarP(&opts.CredentialIdentifiers, "credential-set", "c", nil,
 		"Credential sets to use when running the bundle. It should be a named set of credentials and may be specified multiple times.")
 	f.StringVarP(&opts.Driver, "driver", "d", porter.DefaultDriver,

docs/content/docs/introduction/concepts-and-components/intro-parameters.md

@@ -64,6 +64,56 @@ parameter override is `--param`.
 For example, you may decide to override the `db_name` parameter for a given
 installation via `porter install --param db_name=mydb -p myparamset`.
 
+### Object Parameters from Files
+
+For object-type parameters, you can load JSON data from a file in two ways:
+
+**Using the `@` prefix with CLI flags:**
+
+```bash
+porter install --param [email protected]
+```
+
+The `@` prefix is a convenient shortcut when passing parameters via the command line.
+
+**Using the `path` source in parameter sets:**
+
+For parameter set definitions, use the `path` source to reference files:
+
+```yaml
+schemaType: ParameterSet
+schemaVersion: 1.1.0
+name: myparams
+parameters:
+  - name: config
+    source:
+      path: "/path/to/config.json"
+```
+
+Or in JSON format:
+
+```json
+{
+    "schemaType": "ParameterSet",
+    "schemaVersion": "1.1.0",
+    "name": "myparams",
+    "parameters": [
+        {
+            "name": "config",
+            "source": {
+                "path": "/path/to/config.json"
+            }
+        }
+    ]
+}
+```
+
+This feature:
+- Works with both `--param` CLI flags (using `@` prefix) and parameter sets (using `path` source)
+- The `path` source works for any parameter type, not just objects
+- Validates that the file contains valid JSON for object-type parameters before processing
+- **Security note**: Only user-provided values support file loading. Default values in bundle definitions cannot reference files for security reasons.
+
 When a parameter's bundle definition is set to `sensitive=true`, the user-specified
 value will be stored into a secret store to prevent security leakage. See the [secrets
 plugin docs](/plugins/types/#secrets) to learn how porter uses an external secret store

docs/content/docs/quickstart/parameters.md

@@ -45,14 +45,23 @@ For example:
 porter install --param name=Robin
 ```
 
+For object-type parameters, you can load JSON data from a file by prefixing the file path with `@`:
+
+```
+porter install --param [email protected]
+```
+
+The `@` prefix is supported for CLI parameters, allowing you to manage complex configurations in separate JSON files.
+This is particularly useful for object parameters that contain nested data structures.
+
 When trying out a bundle, it might work well to set individual parameter values on the command line with the --param flag.
 Parameter sets store multiple parameters and pass them to a bundle using the parameter set name.
 With parameter sets you can avoid errors, and the requirement of remembering and manually configuring parameters at the command line.
 Parameter sets store the parameter name, and the source of the parameter value which could be a:
 
 - hard-coded value
 - environment variable
-- file
+- file path
 - command
 - secret
 
@@ -100,7 +109,7 @@ $ cat hello-llama.json
 # modify hello-llama.json with your editor to the content below
 {
     "schemaType": "ParameterSet",
-    "schemaVersion": "1.0.1",
+    "schemaVersion": "1.1.0",
     "name": "hello-llama",
     "parameters": [
         {
@@ -112,7 +121,7 @@ $ cat hello-llama.json
     ]
 }
 $ porter parameters apply hello-llama.json
-Applied /hello-llama parameter se
+Applied /hello-llama parameter set
 ```
 
 This creates a parameter set named hello-llama.

docs/content/docs/references/cli/install.md

@@ -36,6 +36,7 @@ porter install [INSTALLATION] [flags]
   porter install --reference localhost:5000/ghcr.io/getporter/examples/kubernetes:v0.2.0 --insecure-registry --force
   porter install MyAppInDev --file myapp/bundle.json
   porter install --parameter-set azure --param test-mode=true --param header-color=blue
+  porter install --param [email protected]
   porter install --credential-set azure --credential-set kubernetes
   porter install --driver debug
   porter install --label env=dev --label owner=myuser
@@ -59,7 +60,7 @@ porter install [INSTALLATION] [flags]
       --mount-host-volume stringArray   Mount a host volume into the bundle. Format is <host path>:<container path>[:<option>]. May be specified multiple times. Option can be ro (read-only), rw (read-write), default is ro.
   -n, --namespace string                Create the installation in the specified namespace. Defaults to the global namespace.
       --no-logs                         Do not persist the bundle execution logs
-      --param stringArray               Define an individual parameter in the form NAME=VALUE. Overrides parameters otherwise set via --parameter-set. May be specified multiple times.
+      --param stringArray               Define an individual parameter in the form NAME=VALUE. Overrides parameters otherwise set via --parameter-set. May be specified multiple times. For object parameters, use @FILEPATH to load JSON from a file (e.g., --param [email protected]).
   -p, --parameter-set stringArray       Parameter sets to use when running the bundle. It should be a named set of parameters and may be specified multiple times.
   -r, --reference string                Use a bundle in an OCI registry specified by the given reference.
       --verify-bundle                   Verify the bundle signature before executing

docs/content/docs/references/cli/installations_install.md

@@ -36,6 +36,7 @@ porter installations install [INSTALLATION] [flags]
   porter installation install --reference localhost:5000/ghcr.io/getporter/examples/kubernetes:v0.2.0 --insecure-registry --force
   porter installation install MyAppInDev --file myapp/bundle.json
   porter installation install --parameter-set azure --param test-mode=true --param header-color=blue
+  porter installation install --param [email protected]
   porter installation install --credential-set azure --credential-set kubernetes
   porter installation install --driver debug
   porter installation install --label env=dev --label owner=myuser
@@ -59,7 +60,7 @@ porter installations install [INSTALLATION] [flags]
       --mount-host-volume stringArray   Mount a host volume into the bundle. Format is <host path>:<container path>[:<option>]. May be specified multiple times. Option can be ro (read-only), rw (read-write), default is ro.
   -n, --namespace string                Create the installation in the specified namespace. Defaults to the global namespace.
       --no-logs                         Do not persist the bundle execution logs
-      --param stringArray               Define an individual parameter in the form NAME=VALUE. Overrides parameters otherwise set via --parameter-set. May be specified multiple times.
+      --param stringArray               Define an individual parameter in the form NAME=VALUE. Overrides parameters otherwise set via --parameter-set. May be specified multiple times. For object parameters, use @FILEPATH to load JSON from a file (e.g., --param [email protected]).
   -p, --parameter-set stringArray       Parameter sets to use when running the bundle. It should be a named set of parameters and may be specified multiple times.
   -r, --reference string                Use a bundle in an OCI registry specified by the given reference.
       --verify-bundle                   Verify the bundle signature before executing

docs/content/docs/references/cli/installations_invoke.md

@@ -34,6 +34,7 @@ porter installations invoke [INSTALLATION] --action ACTION [flags]
   porter installation invoke --reference localhost:5000/ghcr.io/getporter/examples/kubernetes:v0.2.0 --insecure-registry --force
   porter installation invoke --action ACTION MyAppInDev --file myapp/bundle.json
   porter installation invoke --action ACTION  --parameter-set azure --param test-mode=true --param header-color=blue
+  porter installation invoke --action ACTION --param [email protected]
   porter installation invoke --action ACTION --credential-set azure --credential-set kubernetes
   porter installation invoke --action ACTION --driver debug
 
@@ -56,7 +57,7 @@ porter installations invoke [INSTALLATION] --action ACTION [flags]
       --mount-host-volume stringArray   Mount a host volume into the bundle. Format is <host path>:<container path>[:<option>]. May be specified multiple times. Option can be ro (read-only), rw (read-write), default is ro.
   -n, --namespace string                Namespace of the specified installation. Defaults to the global namespace.
       --no-logs                         Do not persist the bundle execution logs
-      --param stringArray               Define an individual parameter in the form NAME=VALUE. Overrides parameters otherwise set via --parameter-set. May be specified multiple times.
+      --param stringArray               Define an individual parameter in the form NAME=VALUE. Overrides parameters otherwise set via --parameter-set. May be specified multiple times. For object parameters, use @FILEPATH to load JSON from a file (e.g., --param [email protected]).
   -p, --parameter-set stringArray       Parameter sets to use when running the bundle. It should be a named set of parameters and may be specified multiple times.
   -r, --reference string                Use a bundle in an OCI registry specified by the given reference.
 ```

docs/content/docs/references/cli/installations_uninstall.md

@@ -59,7 +59,7 @@ porter installations uninstall [INSTALLATION] [flags]
       --mount-host-volume stringArray   Mount a host volume into the bundle. Format is <host path>:<container path>[:<option>]. May be specified multiple times. Option can be ro (read-only), rw (read-write), default is ro.
   -n, --namespace string                Namespace of the specified installation. Defaults to the global namespace.
       --no-logs                         Do not persist the bundle execution logs
-      --param stringArray               Define an individual parameter in the form NAME=VALUE. Overrides parameters otherwise set via --parameter-set. May be specified multiple times.
+      --param stringArray               Define an individual parameter in the form NAME=VALUE. Overrides parameters otherwise set via --parameter-set. May be specified multiple times. For object parameters, use @FILEPATH to load JSON from a file (e.g., --param [email protected]).
   -p, --parameter-set stringArray       Parameter sets to use when running the bundle. It should be a named set of parameters and may be specified multiple times.
   -r, --reference string                Use a bundle in an OCI registry specified by the given reference.
 ```

docs/content/docs/references/cli/installations_upgrade.md

@@ -34,6 +34,7 @@ porter installations upgrade [INSTALLATION] [flags]
   porter installation upgrade --reference localhost:5000/ghcr.io/getporter/examples/kubernetes:v0.2.0 --insecure-registry --force
   porter installation upgrade MyAppInDev --file myapp/bundle.json
   porter installation upgrade --parameter-set azure --param test-mode=true --param header-color=blue
+  porter installation upgrade --param [email protected]
   porter installation upgrade --credential-set azure --credential-set kubernetes
   porter installation upgrade --driver debug
 
@@ -56,7 +57,7 @@ porter installations upgrade [INSTALLATION] [flags]
       --mount-host-volume stringArray   Mount a host volume into the bundle. Format is <host path>:<container path>[:<option>]. May be specified multiple times. Option can be ro (read-only), rw (read-write), default is ro.
   -n, --namespace string                Namespace of the specified installation. Defaults to the global namespace.
       --no-logs                         Do not persist the bundle execution logs
-      --param stringArray               Define an individual parameter in the form NAME=VALUE. Overrides parameters otherwise set via --parameter-set. May be specified multiple times.
+      --param stringArray               Define an individual parameter in the form NAME=VALUE. Overrides parameters otherwise set via --parameter-set. May be specified multiple times. For object parameters, use @FILEPATH to load JSON from a file (e.g., --param [email protected]).
   -p, --parameter-set stringArray       Parameter sets to use when running the bundle. It should be a named set of parameters and may be specified multiple times.
   -r, --reference string                Use a bundle in an OCI registry specified by the given reference.
       --version string                  Version to which the installation should be upgraded. This represents the version of the bundle, which assumes the convention of setting the bundle tag to its version.