From 90d04b7209af594c10d08e3f0655e1548314930c Mon Sep 17 00:00:00 2001 From: ShakyaPr Date: Wed, 8 Jul 2026 14:30:38 +0530 Subject: [PATCH] add ai workspace cicd flow documentation --- .../ci-cd/configure-ci-cd-workflow.md | 428 ++++++++++++++++++ en/docs/next/ai-workspace/ci-cd/overview.md | 105 +++++ en/docs/next/ai-workspace/overview.md | 12 +- en/mkdocs.yml | 3 + 4 files changed, 547 insertions(+), 1 deletion(-) create mode 100644 en/docs/next/ai-workspace/ci-cd/configure-ci-cd-workflow.md create mode 100644 en/docs/next/ai-workspace/ci-cd/overview.md diff --git a/en/docs/next/ai-workspace/ci-cd/configure-ci-cd-workflow.md b/en/docs/next/ai-workspace/ci-cd/configure-ci-cd-workflow.md new file mode 100644 index 000000000..9a7d734eb --- /dev/null +++ b/en/docs/next/ai-workspace/ci-cd/configure-ci-cd-workflow.md @@ -0,0 +1,428 @@ +--- +title: "Configure an AI Workspace CI/CD workflow" +description: "Use the ap CLI to validate and apply AI Workspace artifacts such as LLM providers, App LLM proxies, and MCP proxies from project files." +canonical_url: https://wso2.com/api-platform/docs/cloud/ai-workspace/ci-cd/configure-ci-cd-workflow/ +md_url: https://wso2.com/api-platform/docs/cloud/ai-workspace/ci-cd/configure-ci-cd-workflow.md +tags: + - cloud + - ai-workspace + - ci-cd +author: WSO2 API Platform Documentation Team +last_updated: 2026-07-08 +content_type: "how-to" +--- + +# Configure an AI Workspace CI/CD Workflow + +This guide shows how to validate and apply AI Workspace artifacts from project files using the `ap` CLI. Use this workflow when you want **LLM providers**, **App LLM proxies**, or **MCP proxies** to be reviewed, versioned, and promoted through a Git-based release process. + +## Prerequisites + +!!! info "Before You Begin" + - Install the `ap` CLI and make it available on your `PATH`. + - Configure access to the target AI Workspace. + - Configure access to the target gateway. + - Start the target AI Gateway with deployment synchronization disabled. + - For App LLM proxy and MCP proxy artifacts, get the API Platform project ID that the artifact belongs to. + - Keep secrets out of project files. Use platform-managed secrets or environment variables supported by the CLI. + +## Configure the AI Workspace Connection + +Add the AI Workspace connection once, then set it as the active workspace for later commands. + +=== "Template" + ```shell + ap ai-workspace add \ + --display-name \ + --server \ + --auth + + ap ai-workspace use --display-name + ``` + +=== "Example" + ```shell + ap ai-workspace add \ + --display-name dev-aiws \ + --server https://ai-workspace.example.com \ + --auth oauth + + ap ai-workspace use --display-name dev-aiws + ``` + +The AI Workspace CLI supports `basic`, `oauth`, and `api-key` authentication. Environment variables override credentials stored in the CLI configuration. + +| Auth type | Environment variables | +|-----------|-----------------------| +| `basic` | `WSO2AP_AIWORKSPACE_USERNAME`, `WSO2AP_AIWORKSPACE_PASSWORD` | +| `oauth` | `WSO2AP_AIWORKSPACE_TOKEN` | +| `api-key` | `WSO2AP_AIWORKSPACE_API_KEY` | + +Configure and select the gateway connection. + +=== "Template" + ```shell + ap gateway add \ + --display-name \ + --server + + ap gateway use --display-name + ``` + +=== "Example" + ```shell + ap gateway add \ + --display-name dev-gw \ + --server https://gateway.example.com + + ap gateway use --display-name dev-gw + ``` + +## Start the Gateway for Declarative CI/CD + +When using this CI/CD flow, start the AI Gateway with control-plane deployment synchronization disabled. + +```toml +[controller.controlplane] +deployment_sync_enabled = false +``` + +In **declarative CI/CD**, AI Workspace artifacts and gateway runtime artifacts are **applied independently** from the project files. Each operation runs **synchronously** and does not rely on output from another service or on **asynchronous gateway-to-control-plane synchronization**. Disabling deployment synchronization prevents the gateway from trying to synchronize deployed artifacts back to AI Workspace while CI/CD owns the artifact lifecycle. + +## Create or Update the Project + +Create a project if you do not already have one. + +=== "Template" + ```shell + ap project init \ + --display-name \ + --type \ + --version \ + --context + + cd + ``` + +=== "Example" + ```shell + ap project init \ + --display-name wso2-claude-proxy \ + --type LLM-Proxy \ + --version v1.0 \ + --context /customer-support + + cd wso2-claude-proxy + ``` + +The project contains the files used by the AI Workspace build and apply commands. + +```text +wso2-claude-proxy/ +|-- metadata.yaml +|-- runtime.yaml +|-- definition.yaml +|-- docs/ +|-- tests/ +`-- .api-platform/ + `-- config.yaml +``` + +## Author the AI Workspace Artifact + +Update `metadata.yaml`, `runtime.yaml`, and `definition.yaml` for the AI Workspace artifact you want to publish. + +The artifact kind in `metadata.yaml` must match the artifact kind in `runtime.yaml` after the `Metadata` suffix is removed. + +| Artifact | `metadata.yaml` kind | `runtime.yaml` kind | +|----------|----------------------|---------------------| +| LLM provider | `LlmProviderMetadata` | `LlmProvider` | +| App LLM proxy | `LlmProxyMetadata` | `LlmProxy` | +| MCP proxy | `McpMetadata` | `Mcp` | + +For example, an App LLM proxy can define its metadata and intended gateways in `metadata.yaml`. + +```yaml +kind: LlmProxyMetadata +metadata: + name: wso2-claude-proxy +spec: + displayName: Customer Support Proxy + version: v1.0 + associatedGateways: + - id: gw-dev + configurations: + host: dev-gateway.example.com +``` + +The corresponding `runtime.yaml` uses the same artifact name and the matching runtime kind. + +```yaml +kind: LlmProxy +metadata: + name: wso2-claude-proxy +spec: + context: /wso2-claude-proxy + description: Proxy endpoint for the customer support assistant. + provider: + id: openai-provider +``` + +Add the OpenAPI or MCP capability definition to `definition.yaml`. The AI Workspace build requires this file for all supported artifact types. + +## Validate the Artifact + +Run `ap ai-workspace build` to validate the project files. If you run the command from the project root, you can omit `-f`. + +=== "Template" + ```shell + # From the project root + ap ai-workspace build + + # From another directory + ap ai-workspace build -f + ``` + +=== "Example" + ```shell + # From the project root + ap ai-workspace build + + # From another directory + ap ai-workspace build -f /path/to/wso2-claude-proxy + ``` + +The build command validates that: + +- `metadata.yaml`, `runtime.yaml`, and `definition.yaml` are available +- the metadata and runtime kinds match +- the metadata names match +- all configured paths remain inside the project directory + +## Deploy the Runtime Artifact to a Gateway + +Apply `runtime.yaml` to the selected gateway so the runtime changes described in the project files are propagated to the gateway in a declarative manner. + +=== "Template" + ```shell + ap gateway apply -f /runtime.yaml + ``` + +=== "Example" + ```shell + ap gateway apply -f /path/to/wso2-claude-proxy/runtime.yaml + ``` + +This deploys or updates the runtime artifact on the active gateway. The AI Workspace apply step is separate and can be run before or after the gateway apply step in the same pipeline, depending on how you structure promotion for the environment. + +## Apply the Artifact to AI Workspace + +Run `ap ai-workspace apply` from the project root, or pass the project directory with `-f`. + +For LLM providers: + +=== "Template" + ```shell + # From the project root + ap ai-workspace apply + + # From another directory + ap ai-workspace apply -f + ``` + +=== "Example" + ```shell + # From the project root + ap ai-workspace apply + + # From another directory + ap ai-workspace apply -f /path/to/openai-provider + ``` + +For App LLM proxies and MCP proxies, include the project ID. + +=== "Template" + ```shell + # From the project root + ap ai-workspace apply --project-id + + # From another directory + ap ai-workspace apply \ + -f \ + --project-id + ``` + +=== "Example" + ```shell + # From the project root + ap ai-workspace apply --project-id customer-support-project + + # From another directory + ap ai-workspace apply \ + -f /path/to/wso2-claude-proxy \ + --project-id customer-support-project + ``` + +The apply command validates the project, builds the request payload in memory, and creates or updates the artifact in AI Workspace. + +| Runtime kind | AI Workspace endpoint | +|--------------|-----------------------| +| `LlmProvider` | `/llm-providers` | +| `LlmProxy` | `/llm-proxies` | +| `Mcp` | `/mcp-proxies` | + +Create and update use the same command. If an artifact with the same `metadata.name` already exists, `apply` updates it. Otherwise, it creates a new artifact. + +## Use Environment-Specific Values + +Use `ENV_CLI_` placeholders for values that differ between environments, such as upstream URLs, hosts, model names, or project IDs. + +```yaml +spec: + upstream: + url: ${ENV_CLI_UPSTREAM_URL} +``` + +Provide the values with an env file during apply. + +=== "Template" + ```shell + ap ai-workspace apply \ + --env-file \ + --project-id + ``` + +=== "Example" + ```shell + ap ai-workspace apply \ + --env-file ./values.env \ + --project-id customer-support-project + ``` + +The CLI resolves placeholders from the file passed with `--env-file`, the project's `.env` file, or the process environment. Apply fails if a referenced placeholder has no value. + +!!! warning "Do not store secrets in project files" + `ENV_CLI_` placeholders are intended for environment-specific configuration values that are sent to AI Workspace. Do not use them for API keys, tokens, or other secrets. Use platform-managed secrets for sensitive values. + +## Example Pipeline + +The following example validates an App LLM proxy or MCP proxy project, applies the runtime artifact to the selected gateway, and applies the AI Workspace artifact to the selected workspace. + +=== "Template" + ```shell + ap gateway use --display-name "" + ap ai-workspace use --display-name "" + + ap ai-workspace build -f + + ap gateway apply -f /runtime.yaml + + ap ai-workspace apply \ + -f \ + --project-id \ + --env-file + ``` + +=== "Example" + ```shell + ap gateway use --display-name "dev-gw" + ap ai-workspace use --display-name "dev-aiws" + + ap ai-workspace build -f /path/to/wso2-claude-proxy + + ap gateway apply -f /path/to/wso2-claude-proxy/runtime.yaml + + ap ai-workspace apply \ + -f /path/to/wso2-claude-proxy \ + --project-id customer-support-project \ + --env-file /path/to/wso2-claude-proxy/values.env + ``` + +For an LLM provider project, omit `--project-id`. + +=== "Template" + ```shell + ap ai-workspace apply \ + -f \ + --env-file + ``` + +=== "Example" + ```shell + ap ai-workspace apply \ + -f /path/to/openai-provider \ + --env-file /path/to/openai-provider/values.env + ``` + +## Verify the Applied Artifact + +Use the AI Workspace get or list commands to verify the result. + +=== "Template" + ```shell + # List LLM providers + ap ai-workspace llm-provider list + + # List App LLM proxies in a project + ap ai-workspace app-llm-proxy list --project-id + + # List MCP proxies in a project + ap ai-workspace mcp-proxy list --project-id + ``` + +=== "Example" + ```shell + # List LLM providers + ap ai-workspace llm-provider list + + # List App LLM proxies in a project + ap ai-workspace app-llm-proxy list --project-id customer-support-project + + # List MCP proxies in a project + ap ai-workspace mcp-proxy list --project-id customer-support-project + ``` + +## AI Workspace CLI Commands + +The following table summarizes the AI Workspace commands available in the `ap` CLI. + +| Command | Description | +|---------|-------------| +| `ap ai-workspace add` | Add an AI Workspace connection to the CLI configuration. | +| `ap ai-workspace list` | List configured AI Workspace connections. | +| `ap ai-workspace remove` | Remove an AI Workspace connection from the CLI configuration. | +| `ap ai-workspace use` | Set the active AI Workspace connection. | +| `ap ai-workspace current` | Show the active AI Workspace connection. | +| `ap ai-workspace build` | Validate the AI Workspace artifact files in a project. | +| `ap ai-workspace apply` | Create or update an AI Workspace artifact from project files. | +| `ap ai-workspace llm-provider list` | List LLM providers in the active organization. | +| `ap ai-workspace llm-provider get` | Get a single LLM provider by ID, or list providers when no ID is provided. | +| `ap ai-workspace llm-provider delete` | Delete an LLM provider by ID. | +| `ap ai-workspace app-llm-proxy list` | List App LLM proxies in a project. | +| `ap ai-workspace app-llm-proxy get` | Get a single App LLM proxy by ID, or list proxies when no ID is provided. | +| `ap ai-workspace app-llm-proxy delete` | Delete an App LLM proxy by ID. | +| `ap ai-workspace mcp-proxy list` | List MCP proxies in a project. | +| `ap ai-workspace mcp-proxy get` | Get a single MCP proxy by ID, or list proxies when no ID is provided. | +| `ap ai-workspace mcp-proxy delete` | Delete an MCP proxy by ID. | + +Use `--help` with any command to view the supported flags and examples. For example: + +```shell +ap ai-workspace apply --help +ap ai-workspace app-llm-proxy list --help +``` + +## Recommended Practices + +- Store the project files in source control. +- Review changes through pull requests before applying them to shared environments. +- Use pipeline variables for target workspace names, gateway names, project IDs, and environment-specific values. +- Keep `metadata.yaml`, `runtime.yaml`, and `definition.yaml` aligned to avoid build failures. +- Avoid changing the same artifact manually in the UI and through CI/CD at the same time. +- Avoid running another synchronization path that updates the same AI Workspace artifact while CI/CD owns it. + +## Next Steps + +- [AI Workspace CI/CD Overview](overview.md) - Learn how the Git-based flow works +- [Configure LLM Provider](../llm-providers/configure-provider.md) - Create and deploy providers from the UI +- [Manage App LLM Proxy](../llm-proxies/manage-proxy.md) - Manage an App LLM proxy after it is created diff --git a/en/docs/next/ai-workspace/ci-cd/overview.md b/en/docs/next/ai-workspace/ci-cd/overview.md new file mode 100644 index 000000000..fb108b823 --- /dev/null +++ b/en/docs/next/ai-workspace/ci-cd/overview.md @@ -0,0 +1,105 @@ +--- +title: "AI Workspace CI/CD overview" +description: "Manage AI Workspace artifacts such as LLM providers, App LLM proxies, and MCP proxies through a Git-based CI/CD workflow." +canonical_url: https://wso2.com/api-platform/docs/cloud/ai-workspace/ci-cd/overview/ +md_url: https://wso2.com/api-platform/docs/cloud/ai-workspace/ci-cd/overview.md +tags: + - cloud + - ai-workspace + - ci-cd +author: WSO2 API Platform Documentation Team +last_updated: 2026-07-08 +content_type: "overview" +--- + +# AI Workspace CI/CD Overview + +AI Workspace CI/CD lets you manage AI Workspace artifacts as version-controlled project files and apply them to the AI Workspace control plane with the `ap` CLI. This gives platform teams a repeatable way to create, update, review, and promote AI artifacts without relying only on manual UI changes. + +You can use this flow for: + +- **LLM providers** - reusable connections to model providers such as OpenAI, Anthropic, Azure OpenAI, Gemini, and Mistral AI +- **App LLM proxies** - application-facing proxy endpoints with their own security, guardrails, policies, and provider reference +- **MCP proxies** - managed proxy endpoints for upstream MCP servers + +## How the CI/CD Flow Works + +In a CI/CD workflow, a project in source control is the source of truth. The project contains declarative files that describe the AI Workspace artifact and the runtime behavior expected by the gateway. + +The high-level flow is: + +1. Start the AI Gateway with control-plane deployment synchronization disabled. +2. Configure the gateway and AI Workspace connections in the `ap` CLI. +3. Create or update an API Platform project. +4. Commit `metadata.yaml`, `runtime.yaml`, and `definition.yaml` to source control. +5. Validate the AI Workspace artifact with `ap ai-workspace build`. +6. Apply the artifact to AI Workspace with `ap ai-workspace apply`. +7. Deploy the runtime artifact to a gateway with `ap gateway apply -f runtime.yaml` so the declarative runtime changes are propagated to the gateway. + +The AI Workspace control plane and gateway runtime do not depend on each other during artifact application. Each operation in the flow is executed synchronously from the project files without relying on output from another service or on asynchronous synchronization. AI Workspace stores the artifact and its intended gateway associations, while the gateway runtime receives runtime artifacts through `ap gateway apply`. + +For this declarative flow, start the AI Gateway with deployment synchronization disabled so the gateway does not try to synchronize deployed artifacts back to AI Workspace: + +```toml +[controller.controlplane] +deployment_sync_enabled = false +``` + +## Project Files + +An AI Workspace CI/CD project uses the same project file model as other API Platform CLI workflows. + +| File | Purpose | +|------|---------| +| `metadata.yaml` | Defines the artifact identity and display metadata. For AI Workspace artifacts, it can also include `spec.associatedGateways`. | +| `runtime.yaml` | Defines the runtime behavior, such as context, provider reference, upstream configuration, security, and policies. Also, this is used to deploy the artifact to the gateway. | +| `definition.yaml` | Defines the OpenAPI or MCP capability definition used when building the AI Workspace payload. This file is required for all supported AI Workspace artifact types. | +| `.api-platform/config.yaml` | Stores project-level CLI configuration, including the AI Workspace file paths used during build and apply. | + +## Supported Artifact Types + +The CLI validates that the artifact kind in `metadata.yaml` matches the kind in `runtime.yaml`. + +| Artifact | `metadata.yaml` kind | `runtime.yaml` kind | +|----------|----------------------|---------------------| +| LLM provider | `LlmProviderMetadata` | `LlmProvider` | +| App LLM proxy | `LlmProxyMetadata` | `LlmProxy` | +| MCP proxy | `McpMetadata` | `Mcp` | + +## Gateway Associations + +Use `spec.associatedGateways` in `metadata.yaml` to record the gateways an AI Workspace artifact is intended to run on. + +```yaml +kind: LlmProxyMetadata +metadata: + name: customer-support-proxy +spec: + displayName: Customer Support Proxy + version: v1.0 + associatedGateways: + - id: gw-dev + configurations: + host: dev-gateway.example.com + - id: gw-prod + configurations: + host: prod-gateway.example.com +``` + +AI Workspace persists these associations during create and update operations and returns them in artifact list and detail responses. The association records the intended gateway targets; it does not create gateway deployment records by itself. + +AI Workspace validates gateway associations within the organization context of the authenticated user. A gateway from another organization cannot be associated with the artifact. + +## CI/CD Benefits + +- **Git-based lifecycle** - Review, version, and promote AI Workspace artifacts through pull requests. +- **Repeatable deployments** - Apply the same project files across environments using pipeline variables. +- **Reduced drift** - Keep UI-managed artifacts aligned with the project files used by CI/CD. +- **Future extensibility** - Use the same build and apply model as more API Platform artifact types are added. + +## Next Steps + +- [Configure an AI Workspace CI/CD Workflow](configure-ci-cd-workflow.md) - Build and apply an AI Workspace artifact with the `ap` CLI +- [Configure LLM Provider](../llm-providers/configure-provider.md) - Create a provider from the AI Workspace UI +- [Configure App LLM Proxy](../llm-proxies/configure-proxy.md) - Create an App LLM proxy from the AI Workspace UI +- [Configure MCP Proxy](../mcp-proxies/configure-proxy.md) - Create an MCP proxy from the AI Workspace UI diff --git a/en/docs/next/ai-workspace/overview.md b/en/docs/next/ai-workspace/overview.md index ea9c6b927..914fb86db 100644 --- a/en/docs/next/ai-workspace/overview.md +++ b/en/docs/next/ai-workspace/overview.md @@ -68,6 +68,16 @@ Expose and govern Model Context Protocol servers through connected gateways. Learn more in [MCP Proxies](mcp-proxies/overview.md). +### CI/CD + +Manage AI Workspace artifacts as project files and apply them through a Git-based release workflow. + +- Version LLM providers, App LLM proxies, and MCP proxies in source control +- Validate project files before applying them to AI Workspace +- Associate artifacts with intended gateway targets during create and update operations + +Learn more in [AI Workspace CI/CD](ci-cd/overview.md). + ### Policies and Guardrails Configure AI-specific governance controls for providers and proxies. @@ -95,4 +105,4 @@ AI Workspace is the control plane. The [AI Gateway](../../cloud/ai-gateway/overv ## Getting Started -To start using the control plane, follow the [Getting Started](getting-started.md) guide. \ No newline at end of file +To start using the control plane, follow the [Getting Started](getting-started.md) guide. diff --git a/en/mkdocs.yml b/en/mkdocs.yml index 5885df986..8f7307a7a 100644 --- a/en/mkdocs.yml +++ b/en/mkdocs.yml @@ -710,6 +710,9 @@ nav: - Publish MCP Proxies: next/ai-workspace/mcp-registry/publish-mcp-proxies.md - Browse the MCP Hub: next/ai-workspace/mcp-registry/browse-mcp-hub.md - Use the MCP Registry API: next/ai-workspace/mcp-registry/mcp-registry-api.md + - CI/CD: + - Overview: next/ai-workspace/ci-cd/overview.md + - Configure CI/CD Workflow: next/ai-workspace/ci-cd/configure-ci-cd-workflow.md - GenAI Applications: next/ai-workspace/genai-applications.md - Configure Inbound Auth: next/ai-workspace/configure-inbound-auth.md - Invoke via SDKs: next/ai-workspace/using-sdks.md