Add documentation for stage providers

docs/symphony-book/providers/stage-providers/create.md

@@ -0,0 +1,55 @@
+# Create stage provider
+
+Create stage provider creates or removes Symphony objects — solution versions or instances — as part of a campaign. When creating an instance, the provider waits until the deployment finishes and reports the result in the outputs.
+
+## Config
+
+| Field | Value |
+|-------|-------|
+| `wait.count` | Maximum number of checks while waiting for a deployment or a deletion to finish. |
+| `wait.interval` | Seconds between checks. Defaults to `20`. |
+
+## Inputs
+
+| Field | Value |
+|-------|-------|
+| `objectType` | `solutionversion` or `instance`. |
+| `objectName` | Name of the object, e.g. `site-app:version1` for a solution version. |
+| `action` | `create` or `remove`. |
+| `object` | Object definition (`metadata` and `spec`), required for the `create` action. |
+| `objectNamespace` | (optional) Namespace of the object. Defaults to `default`. |
+
+## Outputs
+
+| Field | Value |
+|-------|-------|
+| `objectType` | The object type from the inputs. |
+| `objectName` | Name of the created or removed object. |
+| `failedDeploymentCount` | Number of failed deployments when creating an instance. |
+| `status` | `200` on success, `400` when the deployment failed or timed out (instance creation only). |
+| `error` | Error message when `status` is `400`. |
+
+## Sample
+
+Create an instance and branch on the deployment result:
+
+```yaml
+create:
+  name: "create"
+  provider: "providers.stage.create"
+  config:
+    wait.count: 10
+    wait.interval: 20
+  inputs:
+    action: "create"
+    objectName: "site-instance"
+    objectType: "instance"
+    object:
+      metadata:
+        name: site-instance
+      spec:
+        solutionversion: site-app:version1
+        target:
+          name: site-k8s-target
+  stageSelector: ${{$if($equal($output(create, failedDeploymentCount), 0),'succeeded','failed')}}
+```

docs/symphony-book/providers/stage-providers/http.md

@@ -0,0 +1,54 @@
+# Http stage provider
+
+Http stage provider sends an HTTP request to a given URL and captures the response into stage outputs. Request headers and a JSON body can be supplied through inputs. The provider can also poll a second URL until the polled operation reaches a desired state, which is useful for waiting on long-running operations such as Logic Apps workflows.
+
+All configuration fields can be overridden per execution by providing inputs with the same names.
+
+## Config
+
+| Field | Value |
+|-------|-------|
+| `url` | Request URL. |
+| `method` | HTTP method, such as `GET` or `POST`. |
+| `successCodes` | (optional) List of status codes considered successful, such as `[200, 202]`. If set, any other status code fails the stage. |
+| `wait.url` | (optional) URL to poll (with `GET`) after the initial request. |
+| `wait.start` | (optional) Status codes of the initial response that trigger polling. |
+| `wait.success` | (optional) Status codes of the poll response that indicate success. |
+| `wait.fail` | (optional) Status codes of the poll response that indicate failure. |
+| `wait.interval` | (optional) Seconds to wait between polls. |
+| `wait.count` | (optional) Maximum number of polls. `0` means poll until success or failure. |
+| `wait.expression` | (optional) Expression evaluated against the poll response body. Polling stops only when the expression succeeds. |
+| `wait.expressionType` | (optional) `symphony` (default) or `jsonpath` — the expression language of `wait.expression`. |
+
+## Inputs
+
+| Field | Value |
+|-------|-------|
+| `<config field>` | (optional) Any config field listed above, overriding the configured value for this execution. |
+| `header.<name>` | (optional) HTTP request header, e.g. `header.Content-Type`. |
+| `body` | (optional) Request body, serialized as JSON. |
+
+## Outputs
+
+| Field | Value |
+|-------|-------|
+| `status` | Response status code, e.g. `200`. |
+| `body` | Response body as a string. |
+| `header.<name>` | Response headers. |
+| `waitResult` | Result of `wait.expression`, when polling is used. |
+| `waitBody` | Body of the successful poll response, when polling is used. |
+
+## Sample
+
+Call a Logic Apps workflow and continue to the `deploy` stage when the call succeeds:
+
+```yaml
+approval:
+  name: "approval"
+  provider: "providers.stage.http"
+  config:
+    url: "<Logic Apps Workflow URL>"
+    method: "GET"
+    successCodes: [200]
+  stageSelector: ${{$if($equal($output(approval,status), 200),'deploy','end')}}
+```

docs/symphony-book/providers/stage-providers/list.md

@@ -0,0 +1,32 @@
+# List stage provider
+
+List stage provider lists Symphony objects of a given type and puts the result into the stage outputs. Listing `sites` returns the child sites of the current site. The result is typically consumed by a following stage through the `$output()` function, for example to fan out a deployment to multiple sites.
+
+## Inputs
+
+| Field | Value |
+|-------|-------|
+| `objectType` | `instance`, `sites`, or `catalogversions`. |
+| `namesOnly` | (optional) When `true`, `items` contains only the object names instead of the full object states. Defaults to `false`. |
+| `objectNamespace` | (optional) Namespace to list from. Defaults to `default`. Not used for `sites`. |
+
+## Outputs
+
+| Field | Value |
+|-------|-------|
+| `items` | List of objects (or object names when `namesOnly` is `true`). |
+| `objectType` | The object type from the inputs. |
+
+## Sample
+
+List all child sites and pass their names to the next stage:
+
+```yaml
+list:
+  name: "list"
+  provider: providers.stage.list
+  inputs:
+    objectType: sites
+    namesOnly: true
+  stageSelector: wait-sync
+```

docs/symphony-book/providers/stage-providers/materialize.md

@@ -0,0 +1,37 @@
+# Materialize stage provider
+
+Materialize stage provider creates Symphony objects from catalog versions. Each entry in the `names` input references a catalog version whose `spec.properties` holds an embedded object definition; the provider reads each catalog version and creates the embedded object in the given namespace. Supported catalog types are `instance`, `solutionVersion`, `target`, and wrapped `catalogVersion`/`config` objects. Parent containers (solution or catalog) are created automatically when they don't exist.
+
+## Config
+
+| Field | Value |
+|-------|-------|
+| `waitForDeployment` | (optional) When `true`, the provider waits until the deployments of the created instances and targets finish. Currently supported in Kubernetes mode only. |
+| `waitTimeout` | (optional) How long to wait for deployments, e.g. `5m`. Defaults to `5m` when `waitForDeployment` is `true`. |
+
+## Inputs
+
+| Field | Value |
+|-------|-------|
+| `names` | List of catalog version references to materialize, e.g. `gated-prometheus-instance`. |
+| `objectNamespace` | (optional) Namespace in which the objects are created. Defaults to `default`. |
+
+## Outputs
+
+| Field | Value |
+|-------|-------|
+| `failedDeployment` | List of failed deployments (only when `waitForDeployment` is `true`). |
+| `failedDeploymentCount` | Number of failed deployments (only when `waitForDeployment` is `true`). |
+
+## Sample
+
+Materialize an instance from a catalog version:
+
+```yaml
+deploy:
+  name: "deploy"
+  provider: "providers.stage.materialize"
+  inputs:
+    names:
+    - "gated-prometheus-instance"
+```

docs/symphony-book/providers/stage-providers/mock.md

@@ -0,0 +1,30 @@
+# Mock stage provider
+
+Mock stage provider echoes its inputs back as outputs. It also prints the inputs and outputs to the log, which makes it useful for testing campaign flows and for building sample campaigns. As a special case, an input named `foo` is treated as a counter: its integer value is incremented by `1` on every execution (starting from `1` when not set), so a mock stage can loop a configurable number of times when combined with a `stageSelector` expression.
+
+## Inputs
+
+| Field | Value |
+|-------|-------|
+| `<any field>` | Any input field is copied to the outputs as is. |
+| `foo` | (optional) An integer counter that is incremented by `1` on each execution. |
+
+## Outputs
+
+| Field | Value |
+|-------|-------|
+| `<any field>` | A copy of each input field. |
+| `foo` | The incremented counter value, if `foo` was present in the inputs. |
+
+## Sample
+
+Loop the `mock` stage until the `foo` counter reaches `5`:
+
+```yaml
+mock:
+  name: "mock"
+  provider: "providers.stage.mock"
+  inputs:
+    foo: "${{$output(mock,foo)}}"
+  stageSelector: "${{$if($lt($output(mock,foo), 5), mock, '')}}"
+```

docs/symphony-book/providers/stage-providers/patch.md

@@ -0,0 +1,44 @@
+# Patch stage provider
+
+Patch stage provider patches an existing solution version — adding, replacing, or removing a component, or updating a property list of a specific component. The patch content either comes from a catalog version or is given inline in the stage inputs.
+
+## Inputs
+
+| Field | Value |
+|-------|-------|
+| `objectType` | `solutionversion`. |
+| `objectName` | Name of the solution version to patch, e.g. `test-app:version1`. |
+| `patchSource` | (optional) `catalogversion` (default) or `inline`. |
+| `patchContent` | For `catalogversion`: the name of the catalog version that holds the patch. For `inline`: an inline component definition, or a property map when `component` is set. |
+| `component` | (optional) Name of the component to patch. When empty, the whole component from the patch content is added, replaced, or removed. |
+| `property` | (optional) Name of the component property (a list) to patch. |
+| `subKey` | (optional) Key inside a map-typed property that holds the list to patch. |
+| `dedupKey` | (optional) Property used to match existing list entries; matching entries are replaced (or removed) instead of appended. |
+| `patchAction` | (optional) `add` (default) or `remove`. |
+| `objectNamespace` | (optional) Namespace of the object. Defaults to `default`. |
+
+## Outputs
+
+The patch provider doesn't produce outputs.
+
+## Sample
+
+Add a new container component to a solution version:
+
+```yaml
+deploy-v2:
+  name: "deploy-v2"
+  provider: "providers.stage.patch"
+  inputs:
+    objectType: solutionversion
+    objectName: test-app:version1
+    patchSource: inline
+    patchContent:
+      name: backend-v2
+      type: container
+      properties:
+        deployment.replicas: "#1"
+        container.image: "ghcr.io/eclipse-symphony/sample-flask-app:latest"
+    patchAction: add
+  stageSelector: "canary-ingress"
+```

docs/symphony-book/providers/stage-providers/script.md

@@ -0,0 +1,40 @@
+# Script stage provider
+
+Script stage provider runs a bash or PowerShell script as a campaign stage. The script can live in a local folder or be downloaded from a remote URL; remote URLs are validated against the server-side security policy before downloading. On each execution, the stage inputs are written to a JSON file whose path is passed to the script as an argument, and the script writes its results to a second JSON file that becomes the stage outputs.
+
+## Config
+
+| Field | Value |
+|-------|-------|
+| `name` | Provider name. |
+| `script` | Script file name. |
+| `scriptFolder` | (optional) Folder containing the script — a local path or a remote URL. |
+| `stagingFolder` | (optional) Folder for the generated input/output files (and the downloaded script, when remote). |
+| `scriptEngine` | (optional) `bash` (default) or `powershell`. |
+
+## Inputs
+
+| Field | Value |
+|-------|-------|
+| `<any field>` | All inputs are serialized to a JSON file that is passed to the script as its argument. |
+
+## Outputs
+
+| Field | Value |
+|-------|-------|
+| `<any field>` | The contents of the JSON output file written by the script, as key-value pairs. |
+
+## Sample
+
+Run an approval script downloaded from a remote folder, and branch on the `status` value it returns:
+
+```yaml
+approval:
+  name: "approval"
+  provider: "providers.stage.script"
+  config:
+    scriptFolder: "https://raw.githubusercontent.com/eclipse-symphony/symphony/main/docs/samples/approval/script"
+    scriptEngine: "bash"
+    script: "mock-reject.sh"
+  stageSelector: ${{$if($equal($output(approval,status), 200),'deploy','end')}}
+```

docs/symphony-book/providers/stage-providers/wait.md

@@ -0,0 +1,44 @@
+# Wait stage provider
+
+Wait stage provider waits until a list of Symphony objects exists. It polls the object list of the given type and finishes once every named object is found. When the wait runs inside an activation, it also stops if the activation itself is deleted.
+
+## Config
+
+| Field | Value |
+|-------|-------|
+| `wait.interval` | (optional) Seconds to wait between checks. |
+| `wait.count` | (optional) Maximum number of checks. `0` means wait indefinitely. |
+
+## Inputs
+
+| Field | Value |
+|-------|-------|
+| `objectType` | `instance`, `sites`, or `catalogversions`. |
+| `names` | List of object names to wait for. |
+| `objectNamespace` | (optional) Namespace of the objects. Defaults to `default`. Not used for `sites`. |
+
+## Outputs
+
+| Field | Value |
+|-------|-------|
+| `objectType` | The object type from the inputs. |
+| `status` | `200` once all objects are found. |
+
+## Sample
+
+Wait for two instances to be created before moving on:
+
+```yaml
+wait-instances:
+  name: "wait-instances"
+  provider: "providers.stage.wait"
+  config:
+    wait.interval: 20
+    wait.count: 30
+  inputs:
+    objectType: instance
+    names:
+    - "site-instance-1"
+    - "site-instance-2"
+  stageSelector: "next-stage"
+```