diff --git a/pages/api-reference/kubernetes/agent-api-reference.md b/pages/api-reference/kubernetes/agent-api-reference.md index a91e95af..a3dc9a30 100644 --- a/pages/api-reference/kubernetes/agent-api-reference.md +++ b/pages/api-reference/kubernetes/agent-api-reference.md @@ -282,6 +282,7 @@ _Appears in:_ | `agentTTL` _[Duration](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.29/#duration-v1-meta)_ | AgentTTL configures the maximum lifetime for agent run pods on this runtime. When not provided, a default TTL of 12 hours will be used. | | Optional: \{\}
| | `scmConnection` _string_ | ScmConnection is the name of an ScmConnection in Console to use for git operations on agent runs using this runtime.
This should match the name of an existing ScmConnection resource or connection created in the Plural UI. | | Optional: \{\}
| | `exaConnection` _[ExaConnection](#exaconnection)_ | ExaConnection enables Exa web search and content retrieval tools on the Plural MCP server. | | | +| `mcpServers` _[MCPServer](#mcpserver) array_ | MCPServers are additional remote MCP servers made available to coding agents
on this runtime. Servers are expected to already be deployed and reachable
at the given URL. Built-in servers named "plural" and "codebase-memory-mcp"
are reserved and cannot be overridden. | | Optional: \{\}
| #### Binding @@ -585,7 +586,7 @@ _Appears in:_ | Field | Description | Default | Validation | | --- | --- | --- | --- | -| `script` _string_ | | | | +| `script` _string_ | Script is a Lua health-assessment script. The target resource is available as the global `Obj`.
The script must assign a Lua table to the global `healthStatus`; a Lua `return \{ ... \}` is not consumed.
The table uses `status` and an optional `message`, for example: `healthStatus = \{ status = "Healthy", message = "resource is ready" \}`.
Supported/intended status values are `Healthy`, `Degraded`, `Paused`, `Unknown`, `Progressing`, `Suspended`, and `Missing`.
See https://docs.plural.sh/plural-features/continuous-deployment/deployment-operator/custom-health for the full guide. | | | | `group` _string_ | | | Optional: \{\}
| | `version` _string_ | | | Optional: \{\}
| | `kind` _string_ | | | Optional: \{\}
| @@ -851,6 +852,43 @@ _Appears in:_ | `recommendationsSettings` _[RecommendationsSettings](#recommendationssettings)_ | | | Optional: \{\}
| +#### MCPServer + + + +MCPServer is a remote MCP server exposed to agent runtimes. + + + +_Appears in:_ +- [AgentRuntimeSpec](#agentruntimespec) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `name` _string_ | Name is the MCP server identifier used by the coding agent. | | MinLength: 1
Required: \{\}
| +| `url` _string_ | URL is the remote streamable HTTP MCP endpoint. | | MinLength: 1
Required: \{\}
| +| `allowedTools` _string array_ | AllowedTools is an optional allowlist of tool names from this server.
When omitted or empty, all tools advertised by the server are exposed. | | Optional: \{\}
| +| `headers` _[MCPServerHeader](#mcpserverheader) array_ | Headers are HTTP headers sent with requests to this MCP server.
Each header must set exactly one of value or valueFrom. | | Optional: \{\}
| + + +#### MCPServerHeader + + + +MCPServerHeader is an HTTP header for a remote MCP server. + + + +_Appears in:_ +- [MCPServer](#mcpserver) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `name` _string_ | Name is the HTTP header name. | | MinLength: 1
Required: \{\}
| +| `value` _string_ | Value is a literal header value. | | Optional: \{\}
| +| `valueFrom` _[EnvVarSource](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.29/#envvarsource-v1-core)_ | ValueFrom sources the header value the same way as a pod env var. | | Optional: \{\}
| + + #### MetricsAggregate diff --git a/pages/api-reference/kubernetes/management-api-reference.md b/pages/api-reference/kubernetes/management-api-reference.md index f5f7aea1..b2b9f18f 100644 --- a/pages/api-reference/kubernetes/management-api-reference.md +++ b/pages/api-reference/kubernetes/management-api-reference.md @@ -9,6 +9,8 @@ Package v1alpha1 contains API Schema definitions for the deployments v1alpha1 API group ### Resource Types +- [AgentRuntimePolicy](#agentruntimepolicy) +- [BindingPolicy](#bindingpolicy) - [BootstrapToken](#bootstraptoken) - [Catalog](#catalog) - [CloudConnection](#cloudconnection) @@ -39,6 +41,7 @@ Package v1alpha1 contains API Schema definitions for the deployments v1alpha1 AP - [Persona](#persona) - [Pipeline](#pipeline) - [PipelineContext](#pipelinecontext) +- [Policy](#policy) - [PrAutomation](#prautomation) - [PrAutomationTrigger](#prautomationtrigger) - [PrGovernance](#prgovernance) @@ -152,6 +155,63 @@ _Appears in:_ | `template` _string_ | Template the template to use for this callout | | | +#### AgentRuntimePolicy + + + +AgentRuntimePolicy centrally defines who can create agent runs on an AgentRuntime. +Bindings must be managed from the management cluster: if a target cluster could set +its own bindings, cluster operators could grant themselves clone/PR access against +any repository reachable by the runtime's SCM credentials. + + + + + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `apiVersion` _string_ | `deployments.plural.sh/v1alpha1` | | | +| `kind` _string_ | `AgentRuntimePolicy` | | | +| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.29/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. | | | +| `spec` _[AgentRuntimePolicySpec](#agentruntimepolicyspec)_ | | | | + + +#### AgentRuntimePolicyBindings + + + +AgentRuntimePolicyBindings defines create permissions for an AgentRuntime. + + + +_Appears in:_ +- [AgentRuntimePolicySpec](#agentruntimepolicyspec) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `create` _[Binding](#binding) array_ | Create bindings control who can create agent runs on this runtime. | | Optional: \{\}
| + + +#### AgentRuntimePolicySpec + + + +AgentRuntimePolicySpec defines the desired access policy for an AgentRuntime. + + + +_Appears in:_ +- [AgentRuntimePolicy](#agentruntimepolicy) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `runtime` _string_ | Runtime is the name of the AgentRuntime this policy applies to.
Defaults to metadata.name if not specified. | | Optional: \{\}
| +| `bindings` _[AgentRuntimePolicyBindings](#agentruntimepolicybindings)_ | Bindings define who can create agent runs on the targeted runtime. | | Optional: \{\}
| +| `clusterRef` _[ObjectReference](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.29/#objectreference-v1-core)_ | ClusterRef references the target Cluster where this service will be deployed. Leave it as an empty struct to use the cluster field instead. | | Optional: \{\}
| +| `cluster` _string_ | Cluster is the handle of the target Cluster where this service will be deployed. Leave it empty to use the clusterRef field instead. | | Optional: \{\}
| +| `reconciliation` _[Reconciliation](#reconciliation)_ | Reconciliation settings for this resource.
Controls drift detection and reconciliation intervals. | | Optional: \{\}
| + + #### AgentRuntimeRef @@ -345,6 +405,7 @@ Binding used to assign permissions to a resource for a user or a group in the sy _Appears in:_ +- [AgentRuntimePolicyBindings](#agentruntimepolicybindings) - [Bindings](#bindings) - [CatalogBindings](#catalogbindings) - [CloudConnectionSpec](#cloudconnectionspec) @@ -364,6 +425,65 @@ _Appears in:_ | `groupName` _string_ | | | Optional: \{\}
| +#### BindingPolicy + + + +BindingPolicy automatically attaches a Policy to all resources that match +the configured criteria. It references two Policy CRDs: policyRef (the policy +to enforce) and bindPolicyRef (the selector policy that determines which +resources are targeted). The controller polls at the configured interval and +applies the policy to any newly matching targets. + + + + + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `apiVersion` _string_ | `deployments.plural.sh/v1alpha1` | | | +| `kind` _string_ | `BindingPolicy` | | | +| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.29/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. | | | +| `spec` _[BindingPolicySpec](#bindingpolicyspec)_ | Spec reflects a Console API binding policy spec. | | Required: \{\}
| + + +#### BindingPolicyMatches + + + +BindingPolicyMatches defines the criteria used to select targets for a BindingPolicy. + + + +_Appears in:_ +- [BindingPolicySpec](#bindingpolicyspec) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `workbench` _[WorkbenchBindingPolicyMatches](#workbenchbindingpolicymatches)_ | Workbench defines match criteria for workbench-type binding policies. | | Optional: \{\}
| + + +#### BindingPolicySpec + + + +BindingPolicySpec defines the desired state of a BindingPolicy. + + + +_Appears in:_ +- [BindingPolicy](#bindingpolicy) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `type` _[BindingPolicyType](#bindingpolicytype)_ | Type specifies the resource type this binding policy applies to.
Valid values: WORKBENCH, STACK. | | Required: \{\}
| +| `interval` _string_ | Interval controls how often this binding policy is evaluated.
Defaults to 1h; cannot be shorter than 30m. Format: duration string e.g. "1h", "30m". | | Optional: \{\}
| +| `policyRef` _[ObjectReference](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.29/#objectreference-v1-core)_ | PolicyRef references the Policy CRD whose policy will be enforced on matching targets. | | Required: \{\}
| +| `bindPolicyRef` _[ObjectReference](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.29/#objectreference-v1-core)_ | BindPolicyRef references the Policy CRD whose policy determines which targets to bind. | | Required: \{\}
| +| `matches` _[BindingPolicyMatches](#bindingpolicymatches)_ | Matches defines criteria that determine when this binding policy applies. | | Optional: \{\}
| +| `reconciliation` _[Reconciliation](#reconciliation)_ | Reconciliation settings for this resource.
Controls drift detection and reconciliation intervals. | | Optional: \{\}
| + + #### Bindings @@ -881,6 +1001,7 @@ _Appears in:_ | `cloud` _string_ | Cloud specifies the cloud provider to use for this cluster.
Determines the infrastructure platform where the cluster will be provisioned and managed.
For BYOK clusters, this field is set to "byok" and no cloud provider is required.
Deprecated.
Do not use. | | Enum: [aws azure gcp byok]
Optional: \{\}
Type: string
| | `protect` _boolean_ | Protect prevents accidental deletion of this cluster.
When enabled, the cluster cannot be deleted through the Console UI or API.
Deprecated.
Do not use. | | Optional: \{\}
| | `tags` _object (keys:string, values:string)_ | Tags are key-value pairs used to categorize and filter clusters in fleet management.
Used for organizing clusters by environment, team, or other operational criteria. | | Optional: \{\}
| +| `mergeTags` _boolean_ | MergeTags, when true, merges tags specified on this resource with the existing
tags on the tracked Console cluster instead of replacing them. Spec tags overlay
existing tags (the CR wins on key conflicts). Tags previously applied by this
CR and later removed from spec are dropped; tags that were never managed by
this CR are left intact. Only applies when this Cluster is tracking an existing
Console cluster (read-only mode). Defaults to false. | | Optional: \{\}
| | `metadata` _[RawExtension](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.29/#rawextension-runtime-pkg)_ | Refer to Kubernetes API documentation for fields of `metadata`. | | Optional: \{\}
| | `bindings` _[Bindings](#bindings)_ | Bindings contain read and write access policies for this cluster.
Controls which users and groups can view or manage this cluster through RBAC. | | Optional: \{\}
| | `cloudSettings` _[ClusterCloudSettings](#clustercloudsettings)_ | CloudSettings contains cloud provider-specific configuration for this cluster.
Deprecated.
Do not use. | | Optional: \{\}
| @@ -1594,6 +1715,7 @@ _Appears in:_ | `workbenchAssociations` _[FlowWorkbenchAssociation](#flowworkbenchassociation) array_ | WorkbenchAssociations contains a list of workbenches you wish to associate with this flow. | | Optional: \{\}
| | `metadata` _[RawExtension](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.29/#rawextension-runtime-pkg)_ | Refer to Kubernetes API documentation for fields of `metadata`. | | Optional: \{\}
| | `agentRuntime` _[AgentRuntimeRef](#agentruntimeref)_ | AgentRuntime references the agent runtime to use for this flow by cluster handle and runtime name.
The controller resolves this to an agent runtime ID when syncing to the Console API. | | Optional: \{\}
| +| `maxPreviews` _integer_ | MaxPreviews is the maximum number of preview environments allowed for this flow.
Must be between 1 and 25. Defaults to 10 if omitted. | | Maximum: 25
Minimum: 1
Optional: \{\}
| | `reconciliation` _[Reconciliation](#reconciliation)_ | Reconciliation settings for this resource.
Controls drift detection and reconciliation intervals. | | Optional: \{\}
| @@ -3543,6 +3665,26 @@ _Appears in:_ | `urgent` _boolean_ | Urgent controls whether notifications should be immediately delivered via email.
When true, notifications sent to this sink will trigger immediate SMTP delivery
in addition to appearing in the Console UI, useful for critical alerts. | | Optional: \{\}
| +#### Policy + + + +Policy defines a reusable OPA policy that can be attached to resources via BindingPolicy. +Policies contain the actual policy source text (Rego) along with metadata describing +what type of resources they apply to (workbench, stack, or binding). + + + + + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `apiVersion` _string_ | `deployments.plural.sh/v1alpha1` | | | +| `kind` _string_ | `Policy` | | | +| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.29/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. | | | +| `spec` _[PolicySpec](#policyspec)_ | Spec reflects a Console API policy spec. | | Required: \{\}
| + + #### PolicyEngine @@ -3563,6 +3705,27 @@ _Appears in:_ | `git` _[GitRef](#gitref)_ | Git is the ref and folder (within the policy repository or stack repository) for policy files.
If git.url is set, it resolves the repository in Console (same as the stack-level git field); ref and folder are still used for the API. | | Optional: \{\}
| +#### PolicySpec + + + +PolicySpec defines the desired state of a Policy. + + + +_Appears in:_ +- [Policy](#policy) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `name` _string_ | Name is the unique policy name in the Console API.
Defaults to metadata.name if not specified. | | Optional: \{\}
| +| `description` _string_ | Description provides a human-readable explanation of this policy's purpose. | | Optional: \{\}
| +| `type` _[PolicyType](#policytype)_ | Type specifies what kind of resource this policy applies to.
Valid values: WORKBENCH, STACK, BINDING. | | Optional: \{\}
| +| `policy` _string_ | Policy contains the actual policy source text (e.g. Rego for OPA policies). | | Optional: \{\}
| +| `projectRef` _[ObjectReference](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.29/#objectreference-v1-core)_ | ProjectRef links this policy to a specific project.
When set, the policy is scoped to that project. | | Optional: \{\}
| +| `reconciliation` _[Reconciliation](#reconciliation)_ | Reconciliation settings for this resource.
Controls drift detection and reconciliation intervals. | | Optional: \{\}
| + + #### PrAutomation @@ -4111,6 +4274,7 @@ _Appears in:_ | --- | --- | --- | --- | | `name` _string_ | Name specifies the name for this preview environment template.
If not provided, the name from the resource metadata will be used. | | Optional: \{\}
| | `commentTemplate` _string_ | CommentTemplate provides a liquid template for generating custom PR comments.
This template can include dynamic information about the preview environment such as
URLs, deployment status, or custom instructions for reviewers. Variables from the
service template and environment can be interpolated into the comment. | | Optional: \{\}
| +| `previewTtl` _string_ | PreviewTTL specifies how long preview environments created from this template should live,
as a Kubernetes duration (e.g. 1d, 12h, 30m). If omitted, the Console default is used. | | Optional: \{\}
| | `scmConnectionRef` _[ObjectReference](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.29/#objectreference-v1-core)_ | ScmConnectionRef references the source control management connection to use for PR operations.
This connection is used to post comments on pull requests with preview environment information
and to trigger environment creation based on PR events. | | Optional: \{\}
| | `referenceServiceRef` _[ObjectReference](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.29/#objectreference-v1-core)_ | ReferenceServiceRef specifies the existing service deployment to use as a template.
This service will be cloned and customized according to the Template configuration
to create preview environments. The referenced service should be a stable, working
deployment that represents the base configuration for preview environments. | | Required: \{\}
| | `flowRef` _[ObjectReference](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.29/#objectreference-v1-core)_ | FlowRef references the flow that owns and manages this preview environment template.
The flow defines the overall workflow and permissions for creating and managing
preview environments based on this template. | | Required: \{\}
| @@ -4155,6 +4319,7 @@ _Appears in:_ | --- | --- | --- | --- | | `name` _string_ | Name of the project. | | Required: \{\}
Type: string
| | `description` _string_ | Description provides a human-readable explanation of this project's purpose
and the resources it manages within the organizational hierarchy. | | Optional: \{\}
Type: string
| +| `disableInsights` _boolean_ | DisableInsights indicates whether to disable AI insights and vector storage for this project. | | Optional: \{\}
| | `bindings` _[Bindings](#bindings)_ | Bindings contain read and write policies that control access to all resources
within this project, enabling fine-grained permission management and multi-tenancy. | | Optional: \{\}
| | `reconciliation` _[Reconciliation](#reconciliation)_ | Reconciliation settings for this resource.
Controls drift detection and reconciliation intervals. | | Optional: \{\}
| @@ -4191,6 +4356,8 @@ Reconciliation parameters for a specific resource. _Appears in:_ +- [AgentRuntimePolicySpec](#agentruntimepolicyspec) +- [BindingPolicySpec](#bindingpolicyspec) - [BootstrapTokenSpec](#bootstraptokenspec) - [CatalogSpec](#catalogspec) - [CloudConnectionSpec](#cloudconnectionspec) @@ -4220,6 +4387,7 @@ _Appears in:_ - [PersonaSpec](#personaspec) - [PipelineContextSpec](#pipelinecontextspec) - [PipelineSpec](#pipelinespec) +- [PolicySpec](#policyspec) - [PrAutomationSpec](#prautomationspec) - [PrAutomationTriggerSpec](#prautomationtriggerspec) - [PrGovernanceSpec](#prgovernancespec) @@ -4888,6 +5056,9 @@ _Appears in:_ | `luaScript` _string_ | LuaScript to use to generate Helm configuration.
This can ultimately return a lua table with keys "values" and "valuesFiles"
to supply overlays for either dynamically based on git state or other metadata. | | Optional: \{\}
| | `luaFile` _string_ | LuaFile to use to generate Helm configuration.
This can ultimately return a Lua table with keys "values" and "valuesFiles"
to supply overlays for either dynamically based on Git state or other metadata. | | Optional: \{\}
| | `luaFolder` _string_ | a folder of lua files to include in the final script used | | Optional: \{\}
| +| `pythonScript` _string_ | PythonScript to use to generate Helm configuration.
This can ultimately return a dict with keys "values" and "valuesFiles"
to supply overlays for either dynamically based on git state or other metadata. | | Optional: \{\}
| +| `pythonFile` _string_ | PythonFile to use to generate Helm configuration.
This can ultimately return a dict with keys "values" and "valuesFiles"
to supply overlays for either dynamically based on Git state or other metadata. | | Optional: \{\}
| +| `pythonFolder` _string_ | a folder of python files to include in the final script used | | Optional: \{\}
| | `kustomizePostrender` _string_ | KustomizePostrender is a folder containing a kustomization to apply to the result of rendering this service's manifests. | | Optional: \{\}
| @@ -5526,6 +5697,22 @@ Git repository, and agent runtime. | `spec` _[WorkbenchSpec](#workbenchspec)_ | Spec defines the desired state of the Workbench. | | Required: \{\}
| +#### WorkbenchBindingPolicyMatches + + + +WorkbenchBindingPolicyMatches defines regex-based selection criteria for workbench targets. + + + +_Appears in:_ +- [BindingPolicyMatches](#bindingpolicymatches) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `regexes` _string array_ | Regexes is a list of regular expressions that select workbench inputs for this policy. | | Optional: \{\}
| + + #### WorkbenchCodingConfig