From 76ea72237f3346ff157aa8374b9fa800d6498976 Mon Sep 17 00:00:00 2001 From: Brad Ison Date: Fri, 4 Sep 2026 17:11:27 +0200 Subject: [PATCH] [management] Add Agent Network managed proxy to the API spec (#7433) Defines the cloud-side managed gateway provisioning surface (POST/GET /api/integrations/agent-network/managed-proxy) and its response objects so clients consume generated types instead of hand-written ones. POST is idempotent: 202 when the call starts (or restarts) provisioning, 200 when a deployment already exists; 409 names an already-assigned endpoint the managed flow does not own and 503 signals temporarily exhausted endpoint allocation. --- client/proto/generate.sh | 2 +- encryption/testprotos/generate.sh | 4 +- flow/proto/generate.sh | 2 +- shared/management/http/api/generate.sh | 2 +- shared/management/http/api/openapi.yml | 99 +++++++++++++++++++++++++ shared/management/http/api/types.gen.go | 48 ++++++++++++ shared/management/proto/generate.sh | 2 +- shared/signal/proto/generate.sh | 2 +- 8 files changed, 154 insertions(+), 7 deletions(-) diff --git a/client/proto/generate.sh b/client/proto/generate.sh index cea8ae912..d73367d12 100755 --- a/client/proto/generate.sh +++ b/client/proto/generate.sh @@ -1,4 +1,4 @@ -#!/bin/bash +#!/usr/bin/env bash set -e if ! which realpath >/dev/null 2>&1; then diff --git a/encryption/testprotos/generate.sh b/encryption/testprotos/generate.sh index 0ce6ebdea..ffbc481d6 100755 --- a/encryption/testprotos/generate.sh +++ b/encryption/testprotos/generate.sh @@ -1,2 +1,2 @@ -#!/bin/bash -protoc -I testprotos/ testprotos/testproto.proto --go_out=. \ No newline at end of file +#!/usr/bin/env bash +protoc -I testprotos/ testprotos/testproto.proto --go_out=. diff --git a/flow/proto/generate.sh b/flow/proto/generate.sh index 6bbf78e61..a031245fd 100755 --- a/flow/proto/generate.sh +++ b/flow/proto/generate.sh @@ -1,4 +1,4 @@ -#!/bin/bash +#!/usr/bin/env bash set -e if ! which realpath > /dev/null 2>&1 diff --git a/shared/management/http/api/generate.sh b/shared/management/http/api/generate.sh index ba29a6905..8f563e99a 100755 --- a/shared/management/http/api/generate.sh +++ b/shared/management/http/api/generate.sh @@ -1,4 +1,4 @@ -#!/bin/bash +#!/usr/bin/env bash set -e if ! which realpath > /dev/null 2>&1 diff --git a/shared/management/http/api/openapi.yml b/shared/management/http/api/openapi.yml index a0549b077..5ad682c6b 100644 --- a/shared/management/http/api/openapi.yml +++ b/shared/management/http/api/openapi.yml @@ -6443,6 +6443,44 @@ components: - enable_prompt_collection - redact_pii - access_log_retention_days + AgentNetworkManagedProxy: + type: object + description: A NetBird-managed Agent Network gateway deployment. + properties: + id: + type: string + description: Managed proxy deployment ID. + example: "d1m3kebd9pcs0c1pnu7g" + state: + type: string + description: Derived deployment state. `provisioning` until the gateway is rolled out and connected, `ready` while the gateway actively serves the endpoint, `failed` when the rollout reported a failure. + enum: [ "provisioning", "ready", "failed" ] + example: "ready" + endpoint: + type: string + description: The account's gateway hostname. + example: "brave-otter.gateway.netbird.io" + region: + type: string + description: Region of the cluster hosting the deployment. + example: "us-east" + message: + type: string + description: Failure detail reported by the rollout. Only set when state is `failed`. + required: + - id + - state + - endpoint + AgentNetworkManagedProxyConflict: + type: object + description: Conflict body returned when the account already has an Agent Network endpoint that managed provisioning does not own, naming that endpoint. + properties: + endpoint: + type: string + description: The Agent Network endpoint already assigned to the account. + example: "llm.example.com" + required: + - endpoint AgentNetworkBudgetRule: type: object description: Account-level budget rule. A limit-only rule bound to groups and/or users that applies across all policies as a min-wins ceiling. Empty targets means it applies to every caller. @@ -13531,6 +13569,67 @@ paths: "$ref": "#/components/responses/not_found" '500': "$ref": "#/components/responses/internal_error" + /api/integrations/agent-network/managed-proxy: + post: + summary: Provision a managed Agent Network gateway + description: Starts provisioning of a NetBird-managed Agent Network gateway for the account, allocating its endpoint under the managed zone on the first call. Idempotent — answers 202 when this call started (or, after a failure, restarted) provisioning and 200 when a deployment already exists, reporting current state either way. Returns 409 when the account already has an Agent Network endpoint that managed provisioning does not own, and 503 when endpoint allocation is temporarily exhausted. + tags: [ Agent Network ] + security: + - BearerAuth: [ ] + - TokenAuth: [ ] + responses: + '200': + description: A managed gateway deployment already exists; reports its current state. + content: + application/json: + schema: + $ref: '#/components/schemas/AgentNetworkManagedProxy' + '202': + description: Provisioning started, or restarted after a reported failure + content: + application/json: + schema: + $ref: '#/components/schemas/AgentNetworkManagedProxy' + '401': + "$ref": "#/components/responses/requires_authentication" + '403': + "$ref": "#/components/responses/forbidden" + '409': + description: The account already has an Agent Network endpoint not owned by managed provisioning + content: + application/json: + schema: + $ref: '#/components/schemas/AgentNetworkManagedProxyConflict' + '500': + "$ref": "#/components/responses/internal_error" + '503': + description: Endpoint allocation is temporarily exhausted; retry later + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + get: + summary: Retrieve managed Agent Network gateway status + description: Reports the account's managed gateway deployment and its derived state. Returns 404 when the account has no managed deployment. + tags: [ Agent Network ] + security: + - BearerAuth: [ ] + - TokenAuth: [ ] + responses: + '200': + description: The account's managed gateway deployment + content: + application/json: + schema: + $ref: '#/components/schemas/AgentNetworkManagedProxy' + '401': + "$ref": "#/components/responses/requires_authentication" + '403': + "$ref": "#/components/responses/forbidden" + '404': + "$ref": "#/components/responses/not_found" + '500': + "$ref": "#/components/responses/internal_error" /api/agent-network/access-logs: get: summary: List Agent Network access logs diff --git a/shared/management/http/api/types.gen.go b/shared/management/http/api/types.gen.go index d6bebf134..b5a7a80ac 100644 --- a/shared/management/http/api/types.gen.go +++ b/shared/management/http/api/types.gen.go @@ -77,6 +77,27 @@ func (e AgentNetworkConsumptionDimensionKind) Valid() bool { } } +// Defines values for AgentNetworkManagedProxyState. +const ( + AgentNetworkManagedProxyStateFailed AgentNetworkManagedProxyState = "failed" + AgentNetworkManagedProxyStateProvisioning AgentNetworkManagedProxyState = "provisioning" + AgentNetworkManagedProxyStateReady AgentNetworkManagedProxyState = "ready" +) + +// Valid indicates whether the value is a known member of the AgentNetworkManagedProxyState enum. +func (e AgentNetworkManagedProxyState) Valid() bool { + switch e { + case AgentNetworkManagedProxyStateFailed: + return true + case AgentNetworkManagedProxyStateProvisioning: + return true + case AgentNetworkManagedProxyStateReady: + return true + default: + return false + } +} + // Defines values for CreateAzureIntegrationRequestHost. const ( CreateAzureIntegrationRequestHostMicrosoftCom CreateAzureIntegrationRequestHost = "microsoft.com" @@ -2224,6 +2245,33 @@ type AgentNetworkGuardrailRequest struct { Name string `json:"name"` } +// AgentNetworkManagedProxy A NetBird-managed Agent Network gateway deployment. +type AgentNetworkManagedProxy struct { + // Endpoint The account's gateway hostname. + Endpoint string `json:"endpoint"` + + // Id Managed proxy deployment ID. + Id string `json:"id"` + + // Message Failure detail reported by the rollout. Only set when state is `failed`. + Message *string `json:"message,omitempty"` + + // Region Region of the cluster hosting the deployment. + Region *string `json:"region,omitempty"` + + // State Derived deployment state. `provisioning` until the gateway is rolled out and connected, `ready` while the gateway actively serves the endpoint, `failed` when the rollout reported a failure. + State AgentNetworkManagedProxyState `json:"state"` +} + +// AgentNetworkManagedProxyState Derived deployment state. `provisioning` until the gateway is rolled out and connected, `ready` while the gateway actively serves the endpoint, `failed` when the rollout reported a failure. +type AgentNetworkManagedProxyState string + +// AgentNetworkManagedProxyConflict Conflict body returned when the account already has an Agent Network endpoint that managed provisioning does not own, naming that endpoint. +type AgentNetworkManagedProxyConflict struct { + // Endpoint The Agent Network endpoint already assigned to the account. + Endpoint string `json:"endpoint"` +} + // AgentNetworkModelDiscoveryRequest defines model for AgentNetworkModelDiscoveryRequest. type AgentNetworkModelDiscoveryRequest struct { // ApiKey Credential to query the vendor with, for a provider that has not been saved yet. Mutually exclusive with provider_id. diff --git a/shared/management/proto/generate.sh b/shared/management/proto/generate.sh index 7cb0f75a5..2915b7f0c 100755 --- a/shared/management/proto/generate.sh +++ b/shared/management/proto/generate.sh @@ -1,4 +1,4 @@ -#!/bin/bash +#!/usr/bin/env bash set -e if ! which realpath > /dev/null 2>&1 diff --git a/shared/signal/proto/generate.sh b/shared/signal/proto/generate.sh index 720a5ff66..718eae152 100755 --- a/shared/signal/proto/generate.sh +++ b/shared/signal/proto/generate.sh @@ -1,4 +1,4 @@ -#!/bin/bash +#!/usr/bin/env bash set -e if ! which realpath > /dev/null 2>&1