Portal API

Review the Solo Enterprise portal API reference docs.

Packages

portal.solo.io/v1alpha1

portal.solo.io/v1alpha1

Resource Types

ApiDoc
ApiProduct
Portal
PortalConfig
PortalParameters

ApiDoc

ApiDoc represents an API document containing an OpenAPI schema. The schema can be provided inline, fetched from a URL, or fetched from a supported in-cluster resource (e.g., Service or Backend).

Inherits fields from:

TypeMeta

Field	Description	Validation
`apiVersion` string	`portal.solo.io/v1alpha1`
`kind` string	`ApiDoc`
`kind` string	Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds	Optional: {}
`apiVersion` string	APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources	Optional: {}
`metadata` ObjectMeta	Refer to Kubernetes API documentation for fields of `metadata`.	Optional: {}
`spec` ApiDocSpec	spec defines the desired state of the ApiDoc.	Required: {}
`status` ApiDocStatus	status is the current state of the ApiDoc.	Optional: {}

ApiDocReference

ApiDocReference references an ApiDoc resource. Used in PortalConfig to point the web server to the ApiDoc containing the OpenAPI spec.

Appears in:

PortalAPI

Field	Description	Default	Validation
`name` string	name of the ApiDoc.		MinLength: 1 Required: {}
`namespace` string	namespace of the ApiDoc.		MinLength: 1 Required: {}

ApiDocRetryStrategy

ApiDocRetryStrategy configures retries for URL and kube-backed schema fetches.

Appears in:

ApiDocSpec

Field	Description	Validation
`maxAttempts` integer	maxAttempts is the maximum number of fetch attempts.	Minimum: 1 Optional: {}
`delay` Duration	delay is the delay between retry attempts.	Optional: {}
`useBackoff` boolean	useBackoff controls whether retries use exponential backoff.	Optional: {}

ApiDocSelector

ApiDocSelector identifies an ApiDoc by name and namespace for use in apiDocSelectors.

Appears in:

PortalTargetReference

Field	Description	Default	Validation
`name` string	name is the name of the ApiDoc to select.		MinLength: 1 Required: {}
`namespace` string	namespace is the namespace of the ApiDoc to select.		MinLength: 1 Required: {}

ApiDocSource

ApiDocSource defines the source of the OpenAPI schema. Exactly one source type must be specified.

Validation:

ExactlyOneOf: [manual url kube stitched]

Appears in:

ApiDocSpec

Field	Description	Validation
`manual` ManualSource	manual specifies the OpenAPI schema content directly in the spec. Use for small, static schemas that don’t change frequently.	Optional: {}
`url` URLSource	url specifies an internal or external URL to fetch the OpenAPI schema from.	Optional: {}
`kube` KubeSource	kube specifies a Kubernetes target (Service or Backend) to fetch the OpenAPI schema from via HTTP.	Optional: {}
`stitched` StitchedSource	stitched specifies that this ApiDoc contains a stitched/projected schema generated by the ApiProduct controller. The schema is derived from one or more source ApiDocs and has paths rewritten according to the ApiProduct’s routing configuration. This source type is controller-managed and should not be set by users directly.	Optional: {}

ApiDocSpec

ApiDocSpec defines the desired state of ApiDoc.

Appears in:

ApiDoc

Field	Description	Validation
`source` ApiDocSource	source defines where to obtain the OpenAPI schema.	ExactlyOneOf: [manual url kube stitched] Required: {}
`servedBy` ServedBy	servedBy anchors this API doc to a backend for Try-It-Out functionality. Required for manual and url sources to enable routing resolution. For kube sources, if omitted, the controller will infer servedBy from spec.source.kube.targetRef. In case you want to override the inferred servedBy, you can set servedBy explicitly. It supports any GVK that contributes to the kgateway routing model, including core Services and kgateway Backends.	Optional: {}
`retry` ApiDocRetryStrategy	retry overrides the controller’s schema fetch retry behavior for url and kube sources. Any field left unset inherits the controller-level default.	Optional: {}

ApiDocStatus

ApiDocStatus defines the observed state of ApiDoc.

Appears in:

ApiDoc

Field	Description	Validation
`conditions` Condition array	conditions represent the current state of the ApiDoc. The “Ready” condition indicates whether the schema is valid and available.	Optional: {}
`sourceType` string	sourceType indicates the source type of this ApiDoc (kube, url, manual, stitched). This is set by the controller based on spec.source and used for display purposes.	Optional: {}
`resolvedSchema` string	resolvedSchema contains the resolved OpenAPI schema. This is the raw schema that has been normalized to OpenAPI 3.x JSON.	Optional: {}

ApiProduct

ApiProduct groups one or more API versions together as a logical product for exposure in the developer portal.

Inherits fields from:

TypeMeta

Field	Description	Validation
`apiVersion` string	`portal.solo.io/v1alpha1`
`kind` string	`ApiProduct`
`kind` string	Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds	Optional: {}
`apiVersion` string	APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources	Optional: {}
`metadata` ObjectMeta	Refer to Kubernetes API documentation for fields of `metadata`.	Optional: {}
`spec` ApiProductSpec	spec defines the desired state of the ApiProduct	Required: {}
`status` ApiProductStatus	status defines the observed state of the ApiProduct	Optional: {}

ApiProductSpec

ApiProductSpec defines the desired state of ApiProduct.

Appears in:

ApiProduct

Field	Description	Validation
`id` string	id is a URL-safe, unique identifier for this API product in the portal.	MaxLength: 128 MinLength: 1 Pattern: `^[a-zA-Z0-9]([-a-zA-Z0-9]*[a-zA-Z0-9])?$` Required: {}
`displayName` string	displayName is the name for the API product to display in the frontend portal. If omitted, the ID value is used as the display name.	MaxLength: 128 MinLength: 1 Optional: {}
`versions` Version array	versions is the list of versions of the API product.	MaxItems: 8 MinItems: 1 Required: {}
`customMetadata` object (keys:string, values:string)	customMetadata provides key-value pairs of custom metadata to display in the developer portal. This metadata applies to the API product as a whole (i.e., across all versions).	MaxProperties: 16 MinProperties: 1 Optional: {}

ApiProductStatus

ApiProductStatus defines the observed state of ApiProduct.

Appears in:

ApiProduct

Field	Description	Default	Validation
`conditions` Condition array	conditions describe the current conditions of the ApiProduct.		MaxItems: 8 Optional: {}
`versions` ApiProductVersionStatus array	versions contains the status of each version defined in spec.versions.		Optional: {}

ApiProductVersionStatus

ApiProductVersionStatus defines the observed state of a single ApiProduct version.

Appears in:

ApiProductStatus

Field	Description	Validation
`conditions` Condition array	conditions describe the current conditions of this version.	MaxItems: 8 Optional: {}
`name` string	name is the version name, matching spec.versions[].name.	MinLength: 1 Required: {}
`generatedApiDocRef` GeneratedApiDocRef	generatedApiDocRef references the ApiDoc generated for this version. This ApiDoc is managed by the controller and contains the stitched/projected OpenAPI schema for this version. Nil if the version failed to process.	Optional: {}

GeneratedApiDocRef

GeneratedApiDocRef is a reference to a generated ApiDoc.

Appears in:

ApiProductVersionStatus

Field	Description	Default	Validation
`name` string	name is the name of the generated ApiDoc.		MinLength: 1 Required: {}
`namespace` string	namespace is the namespace of the generated ApiDoc.		MinLength: 1 Required: {}

KubeSource

KubeSource specifies an in-cluster Kubernetes target to fetch OpenAPI from.

Appears in:

ApiDocSource

Field	Description	Default	Validation
`targetRef` BackendObjectReference	targetRef references the Kubernetes resource to fetch the OpenAPI schema from. Currently supports core Services or gateway.kgateway.dev Backends.		Required: {}
`path` string	path is the HTTP path to fetch the OpenAPI schema from. Example: “/openapi”, “/swagger.json”, “/v3/api-docs”		MaxLength: 1024 MinLength: 1 Pattern: `^/` Required: {}

LocalSecretReference

LocalSecretReference identifies a Secret in the same namespace.

Appears in:

PostgresStoreConfig
PostgresTLSConfig

Field	Description	Default	Validation
`name` ObjectName	name is the name of the Secret.		MaxLength: 253 MinLength: 1 Required: {}

ManualSource

ManualSource specifies the OpenAPI schema content directly.

Appears in:

ApiDocSource

Field	Description	Default	Validation
`content` string	content is the raw OpenAPI schema in JSON or YAML format.		MaxLength: 700000 MinLength: 1 Required: {}

MemoryStoreConfig

MemoryStoreConfig configures an in-memory data store for the portal backend. This store is ephemeral and data is lost on pod restart.

Appears in:

StoreConfig

OpenAPIMetadata

OpenAPIMetadata is the metadata for the OpenAPI specification for a given API product version. When configured, at least one field should be set.

Appears in:

Version

Field	Description	Validation
`title` string	title is the title of the OpenAPI specification for this API.	MaxLength: 256 MinLength: 1 Optional: {}
`description` string	description is the description of the OpenAPI specification for this API.	MaxLength: 1024 MinLength: 1 Optional: {}
`termsOfService` string	termsOfService is a URL to the terms of service for this API.	MaxLength: 512 MinLength: 1 Optional: {}
`contact` string	contact is the contact information for this API. It may be an email address, a URL, or a contact name. A value that parses as an email is treated as an email address; a value that parses as a URL is treated as a URL; any other value is treated as a contact name. Email takes precedence, then URL. A URL must include a scheme (e.g. “https://”) to be recognized as one; a bare host like “www.example.com” is treated as a contact name.	MaxLength: 256 MinLength: 1 Optional: {}
`license` string	license is the license name or identifier for this API (e.g., “MIT”, “Apache-2.0”).	MaxLength: 256 MinLength: 1 Optional: {}

Portal

Portal represents a developer portal deployment that references a PortalParameters resource for operational configuration.

The Portal controller deploys only the backend web server. Users are responsible for:

Deploying the frontend UI (see dev-portal-starter or custom implementation)
Creating Gateway and HTTPRoutes to expose the portal
Configuring authentication (AuthConfig, traffic policies) if needed

See: https://docs.solo.io/gateway/latest/portal/guides/frontend-portal/

To prevent naming collisions, a Portal cannot be named “{name}” if an existing Gateway in the same namespace is already named “portal-{name}”. This is because both resources will attempt to manage data plane components (such as Deployments and Services) using the “portal-{name}” identifier.

Inherits fields from:

TypeMeta

Field	Description	Validation
`apiVersion` string	`portal.solo.io/v1alpha1`
`kind` string	`Portal`
`kind` string	Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds	Optional: {}
`apiVersion` string	APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources	Optional: {}
`metadata` ObjectMeta	Refer to Kubernetes API documentation for fields of `metadata`.	Optional: {}
`spec` PortalSpec	spec defines the desired state of the Portal	Required: {}
`status` PortalStatus	status defines the observed state of the Portal	Optional: {}

PortalAPI

PortalAPI represents an API product version in the portal

Appears in:

PortalConfigSpec

Field	Description	Validation
`apiProductId` string	apiProductId is the unique identifier for the API product	MinLength: 1 Required: {}
`apiProductDisplayName` string	apiProductDisplayName is the display name for the API product	Required: {}
`apiVersion` string	apiVersion is the version string (e.g., “v1”, “v2”)	MinLength: 1 Required: {}
`title` string	title from OpenAPI metadata	Optional: {}
`description` string	description from OpenAPI metadata	Optional: {}
`termsOfService` string	termsOfService from OpenAPI metadata	Optional: {}
`contact` string	contact from OpenAPI metadata	Optional: {}
`license` string	license from OpenAPI metadata	Optional: {}
`apiProductCustomMetadata` object (keys:string, values:string)	apiProductCustomMetadata from ApiProduct.spec.customMetadata	Optional: {}
`apiVersionCustomMetadata` object (keys:string, values:string)	apiVersionCustomMetadata from ApiProduct.spec.versions[].customMetadata	Optional: {}
`apiDocRef` ApiDocReference	apiDocRef references the ApiDoc containing the OpenAPI spec. Web server fetches the spec from ApiDoc on-demand to avoid etcd size limits.	Optional: {}

PortalConfig

PortalConfig is the intermediate representation for a Portal’s API catalog. Generated by the Portal Controller, consumed by the Portal Web Server.

Inherits fields from:

TypeMeta

Field	Description	Validation
`apiVersion` string	`portal.solo.io/v1alpha1`
`kind` string	`PortalConfig`
`kind` string	Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds	Optional: {}
`apiVersion` string	APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources	Optional: {}
`metadata` ObjectMeta	Refer to Kubernetes API documentation for fields of `metadata`.	Optional: {}
`spec` PortalConfigSpec	spec defines the API catalog for this portal	Required: {}

PortalConfigSpec

PortalConfigSpec defines the desired state of PortalConfig

Appears in:

PortalConfig

Field	Description	Validation
`apis` PortalAPI array	apis is the list of API products/versions visible in this portal	Optional: {}
`portalMetadata` PortalMetadata	portalMetadata contains portal-level configuration	Required: {}
`visibility` PortalConfigVisibility	visibility controls the access requirements for viewing the portal’s API catalog.	Optional: {}

PortalConfigVisibility

PortalConfigVisibility is the internal representation of PortalVisibility consumed by the portal web backend.

Appears in:

PortalConfigSpec

Field	Description	Default	Validation
`public` boolean	public controls whether the portal’s API catalog is publicly accessible without authentication.		Optional: {}

PortalMetadata

PortalMetadata contains portal branding and configuration

Appears in:

PortalConfigSpec

Field	Description	Default	Validation
`name` string	name is the portal’s display name		MinLength: 1 Required: {}

PortalParameters

PortalParameters defines operational configuration for a Portal deployment, including data store settings and postgres connection details.

Inherits fields from:

TypeMeta

Field	Description	Validation
`apiVersion` string	`portal.solo.io/v1alpha1`
`kind` string	`PortalParameters`
`kind` string	Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds	Optional: {}
`apiVersion` string	APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources	Optional: {}
`metadata` ObjectMeta	Refer to Kubernetes API documentation for fields of `metadata`.
`spec` PortalParametersSpec	spec defines the desired operational configuration for the Portal	Required: {}
`status` PortalParametersStatus	Status defines the observed state of the PortalParameters	Optional: {}

PortalParametersReference

PortalParametersReference identifies a PortalParameters resource in the same namespace.

Appears in:

PortalSpec

Field	Description	Default	Validation
`name` ObjectName	name is the name of the PortalParameters resource.		MaxLength: 253 MinLength: 1 Required: {}

PortalParametersSpec

PortalParametersSpec defines the desired operational configuration for a Portal deployment.

Appears in:

PortalParameters

Field	Description	Validation
`store` StoreConfig	store configures the data store for the portal backend. Exactly one store type must be specified. If omitted, defaults to in-memory.	ExactlyOneOf: [memory postgres] Optional: {}
`webServer` PortalWebServer	webServer configures the portal web server deployment.	Optional: {}
`idpServerURL` string	idpServerURL is the URL of an Identity Provider SPI server for OAuth client management. When set, OAuth credential create/delete operations are delegated to this external server (e.g., Keycloak via gloo-portal-idp-connect). When omitted, oauth endpoint will return a 500.	Optional: {}

PortalParametersStatus

PortalParametersStatus defines the observed state of PortalParameters.

Appears in:

PortalParameters

PortalSpec

PortalSpec defines the desired state of Portal

Appears in:

Portal

Field	Description	Validation
`parametersRef` PortalParametersReference	parametersRef references the PortalParameters resource in the same namespace that defines the operational configuration for this portal. If not specified, the controller uses default in-memory configuration.	Optional: {}
`apiProductRefs` NamespacedObjectReference array	apiProductRefs lists the ApiProducts visible in this portal. Only the referenced ApiProducts will be exposed to end users via the portal’s API catalog. If empty, no API products are exposed.	Optional: {}
`visibility` PortalVisibility	visibility controls the access requirements for the portal’s API catalog.	Optional: {}

PortalStatus

PortalStatus defines the observed state of Portal

Appears in:

Portal

Field	Description	Default	Validation
`conditions` Condition array	conditions represent the latest available observations of the Portal state		Optional: {}

PortalTargetReference

PortalTargetReference extends LocalPolicyTargetReference with portal-specific fields for controlling ApiDoc selection when multiple ApiDocs serve the same backend.

Appears in:

Version

Field	Description	Validation
`group` Group	The API group of the target resource. For Kubernetes Gateway API resources, the group is `gateway.networking.k8s.io`.	MaxLength: 253 Pattern: `^$\|^[a-z0-9]([-a-z0-9][a-z0-9])?(\.[a-z0-9]([-a-z0-9][a-z0-9])?)*$` Required: {}
`kind` Kind	The API kind of the target resource, such as Gateway or HTTPRoute.	MaxLength: 63 MinLength: 1 Pattern: `^[a-zA-Z]([-a-zA-Z0-9]*[a-zA-Z0-9])?$` Required: {}
`name` ObjectName	The name of the target resource.	MaxLength: 253 MinLength: 1 Required: {}
`apiDocSelectors` ApiDocSelector array	apiDocSelectors specifies which ApiDocs to use for schema stitching when multiple ApiDocs serve the same backend referenced by this HTTPRoute. Each selector references an ApiDoc by name and namespace; the target backend is inferred from the ApiDoc’s spec.servedBy field. When omitted, automatic 1:1 backend-to-ApiDoc resolution is used. If multiple ApiDocs match the same backend and no selector is provided, the version fails with an error.	MaxItems: 16 MinItems: 1 Optional: {}

PortalVisibility

PortalVisibility controls the access requirements for viewing the portal’s API catalog

Appears in:

PortalSpec

Field	Description	Default	Validation
`public` boolean	public controls whether the portal’s API catalog is publicly accessible without authentication. When true, unauthenticated users can browse the API catalog. When false (default), users must be logged in to view the catalog content.		Optional: {}

PortalWebServer

PortalWebServer configures the portal web server deployment.

Appears in:

PortalParametersSpec

Inherits fields from:

GatewayParametersOverlays

Field	Description	Validation
`replicas` integer	replicas is the number of portal web server pods. If omitted, defaults to 1. If using an HPA, do not set this field.	Minimum: 0 Optional: {}
`resources` ResourceRequirements	resources configures CPU and memory requests/limits for the portal web server container.	Optional: {}
`container` PortalWebServerContainer	container configures the portal web server container.	Optional: {}
`deploymentOverlay` KubernetesResourceOverlay	deploymentOverlay allows specifying overrides for the generated Deployment resource.	Optional: {}
`serviceOverlay` KubernetesResourceOverlay	serviceOverlay allows specifying overrides for the generated Service resource.	Optional: {}
`serviceAccountOverlay` KubernetesResourceOverlay	serviceAccountOverlay allows specifying overrides for the generated ServiceAccount resource.	Optional: {}
`podDisruptionBudget` KubernetesResourceOverlay	podDisruptionBudget allows creating a PodDisruptionBudget for the proxy. If absent, no PDB is created. If present, a PDB is created with its selector automatically configured to target the proxy Deployment. The metadata and spec fields from this overlay are applied to the generated PDB.	Optional: {}
`horizontalPodAutoscaler` KubernetesResourceOverlay	horizontalPodAutoscaler allows creating a HorizontalPodAutoscaler for the proxy. If absent, no HPA is created. If present, an HPA is created with its scaleTargetRef automatically configured to target the proxy Deployment. The metadata and spec fields from this overlay are applied to the generated HPA.	Optional: {}
`verticalPodAutoscaler` KubernetesResourceOverlay	verticalPodAutoscaler allows creating a VerticalPodAutoscaler for the proxy. If absent, no VPA is created. If present, a VPA is created with its targetRef automatically configured to target the proxy Deployment. The metadata and spec fields from this overlay are applied to the generated VPA.	Optional: {}

PortalWebServerContainer

PortalWebServerContainer configures the portal web server container.

Appears in:

PortalWebServer

Field	Description	Default	Validation
`image` Image	image overrides the portal web server container image. Individual fields (registry, repository, tag, pullPolicy) can be set independently; unset fields retain the chart defaults.		Optional: {}

PostgresSSLMode

Underlying type: string

Validation:

Enum: [disable require verify-ca verify-full]

Appears in:

PostgresTLSConfig

Field	Description
`disable`
`require`
`verify-ca`
`verify-full`

PostgresStoreConfig

PostgresStoreConfig configures a PostgreSQL data store for the portal backend.

Appears in:

StoreConfig

Field	Description	Validation
`secretRef` LocalSecretReference	secretRef references a Secret containing postgres connection credentials. Required keys: host, database, username, password Optional keys: port (default: 5432), sslmode (default: require)	Required: {}
`tls` PostgresTLSConfig	tls configures TLS for the postgres connection.	Optional: {}
`schema` string	schema is the PostgreSQL schema name for portal tables. Defaults to “portal” if not specified.	MaxLength: 63 Pattern: `^[a-zA-Z_][a-zA-Z0-9_]*$` Optional: {}

PostgresTLSConfig

PostgresTLSConfig configures TLS settings for the postgres connection.

Appears in:

PostgresStoreConfig

Field	Description	Validation
`mode` PostgresSSLMode	mode is the SSL mode for postgres: disable, require, verify-ca, verify-full. Overrides the sslmode key in the credentials secret if both are set.	Enum: [disable require verify-ca verify-full] Optional: {}
`caCertSecretRef` LocalSecretReference	caCertSecretRef references a Secret containing a CA certificate (key: “ca.crt”) for verifying the postgres server. Required for verify-ca and verify-full modes.	Optional: {}
`clientCertSecretRef` LocalSecretReference	clientCertSecretRef references a Secret containing a client certificate and key (keys: “tls.crt”, “tls.key”) for mutual TLS authentication with postgres.	Optional: {}

ServedBy

ServedBy specifies the backend that this ApiDoc is anchored to.

Appears in:

ApiDocSpec

Inherits fields from:

BackendObjectReference

Field	Description	Default	Validation
`group` Group	Group is the group of the referent. For example, “gateway.networking.k8s.io”. When unspecified or empty string, core API group is inferred.		MaxLength: 253 Pattern: `^$\|^[a-z0-9]([-a-z0-9][a-z0-9])?(\.[a-z0-9]([-a-z0-9][a-z0-9])?)*$` Optional: {}
`kind` Kind	Kind is the Kubernetes resource kind of the referent. For example “Service”. Defaults to “Service” when not specified. ExternalName services can refer to CNAME DNS records that may live outside of the cluster and as such are difficult to reason about in terms of conformance. They also may not be safe to forward to (see CVE-2021-25740 for more information). Implementations SHOULD NOT support ExternalName Services. Support: Core (Services with a type other than ExternalName) Support: Implementation-specific (Services with type ExternalName)	Service	MaxLength: 63 MinLength: 1 Pattern: `^[a-zA-Z]([-a-zA-Z0-9]*[a-zA-Z0-9])?$` Optional: {}
`name` ObjectName	Name is the name of the referent.		MaxLength: 253 MinLength: 1 Required: {}
`namespace` Namespace	Namespace is the namespace of the backend. When unspecified, the local namespace is inferred. Note that when a namespace different than the local namespace is specified, a ReferenceGrant object is required in the referent namespace to allow that namespace’s owner to accept the reference. See the ReferenceGrant documentation for details. Support: Core		MaxLength: 63 MinLength: 1 Pattern: `^[a-z0-9]([-a-z0-9]*[a-z0-9])?$` Optional: {}
`port` PortNumber	Port specifies the destination port number to use for this resource. Port is required when the referent is a Kubernetes Service. In this case, the port number is the service port number, not the target port. For other resources, destination port might be derived from the referent resource or this field.		Maximum: 65535 Minimum: 1 Optional: {}

StitchedSource

StitchedSource indicates this ApiDoc contains a controller-generated stitched schema. The schema is projected from source ApiDocs according to ApiProduct routing configuration.

Appears in:

ApiDocSource

Field	Description	Default	Validation
`content` string	content is the stitched OpenAPI schema in JSON format. This is generated by the ApiProduct controller and should not be modified directly. MaxLength MUST stay in sync with MaxStitchedContentLength.		MaxLength: 700000 MinLength: 1 Required: {}

StoreConfig

StoreConfig configures the data store for the portal backend. Exactly one store type must be specified.

Validation:

ExactlyOneOf: [memory postgres]

Appears in:

PortalParametersSpec

Field	Description	Default	Validation
`memory` MemoryStoreConfig	memory selects the in-memory data store.		Optional: {}
`postgres` PostgresStoreConfig	postgres selects a PostgreSQL data store.		Optional: {}

URLSource

URLSource specifies an external URL to fetch the OpenAPI schema from.

Appears in:

ApiDocSource

Field	Description	Default	Validation
`endpoint` string	endpoint is the URL to fetch the OpenAPI schema from. Must be a valid HTTP or HTTPS URL.		MinLength: 1 Pattern: `^https?://` Required: {}

Version

Version defines a version of an API product.

Appears in:

ApiProductSpec

Field	Description	Validation
`name` string	name is the version identifier (e.g., “v1”, “v2”, “1.0.0”). It must be unique within the ApiProduct’s versions list.	MaxLength: 32 MinLength: 1 Pattern: `^[a-zA-Z0-9][a-zA-Z0-9._-]*$` Required: {}
`targetRefs` PortalTargetReference array	targetRefs references the HTTPRoutes that expose this API version. Only HTTPRoutes attached to kgateway enterprise Gateways are currently supported.	MaxItems: 8 MinItems: 1 Required: {}
`openApiMetadata` OpenAPIMetadata	openApiMetadata sets the OpenAPI specification metadata for the API product version.	Optional: {}
`customMetadata` object (keys:string, values:string)	customMetadata provides key-value pairs of custom metadata to display in the developer portal. This metadata applies to this specific version of the API product.	MaxProperties: 16 MinProperties: 1 Optional: {}

Shared Types

The following types are defined in the shared package and used across multiple APIs.

Image

A container image. See https://kubernetes.io/docs/concepts/containers/images for details.

Field	Type	Description
`registry`	*string	The image registry.
`repository`	*string	The image repository (name).
`tag`	*string	The image tag.
`digest`	*string	The hash digest of the image, e.g. `sha256:12345...`
`pullPolicy`	*corev1.PullPolicy	The image pull policy for the container. See https://kubernetes.io/docs/concepts/containers/images/#image-pull-policy for details.

KubernetesResourceOverlay

KubernetesResourceOverlay provides a mechanism to customize generated Kubernetes resources using Strategic Merge Patch semantics. # Overlay Application Order Overlays are applied after all typed configuration fields have been processed. The full merge order is: 1. GatewayClass typed configuration fields (e.g., replicas, image settings from parametersRef) 2. Gateway typed configuration fields (from infrastructure.parametersRef) 3. GatewayClass overlays are applied 4. Gateway overlays are applied This ordering means Gateway-level configuration overrides GatewayClass-level configuration at each stage. For example, if both levels set the same label, the Gateway value wins.

Field	Type	Description
`metadata`	*ObjectMetadata	metadata defines a subset of object metadata to be customized. Labels and annotations are merged with existing values. If both GatewayClass and Gateway parameters define the same label or annotation key, the Gateway value takes precedence (applied second).
`spec`	*apiextensionsv1.JSON	Spec provides an opaque mechanism to configure the resource Spec. This field accepts a complete or partial Kubernetes resource spec (e.g., PodSpec, ServiceSpec) and will be merged with the generated configuration using Strategic Merge Patch semantics. # Application Order Overlays are applied after all typed configuration fields from both levels. The full merge order is: 1. GatewayClass typed configuration fields 2. Gateway typed configuration fields 3. GatewayClass overlays 4. Gateway overlays (can override all previous values) # Strategic Merge Patch & Deletion Guide This merge strategy allows you to override individual fields, merge lists, or delete items without needing to provide the entire resource definition. 1. Replacing Values (Scalars): Simple fields (strings, integers, booleans) in your config will overwrite the generated defaults. 2. Merging Lists (Append/Merge): Lists with “merge keys” (like `containers` which merges on `name`, or `tolerations` which merges on `key`) will append your items to the generated list, or update existing items if keys match. 3. Deleting Fields or List Items ($patch: delete): To remove a field or list item from the generated resource, use the `$patch: delete` directive. This works for both map fields and list items, and is the recommended approach because it works with both client-side and server-side apply. spec: template: spec: # Delete pod-level securityContext securityContext: $patch: delete # Delete nodeSelector nodeSelector: $patch: delete containers: # Be sure to use the correct proxy name here or you will add a container instead of modifying a container: - name: proxy-name # Delete container-level securityContext securityContext: $patch: delete 4. Null Values (server-side apply only): Setting a field to `null` can also remove it, but this ONLY works with `kubectl apply --server-side` or equivalent. With regular client-side `kubectl apply`, null values are stripped by kubectl before reaching the API server, so the deletion won’t occur. Prefer `$patch: delete` for consistent behavior across both apply modes. spec: template: spec: nodeSelector: null # Removes nodeSelector (server-side apply only!) 5. Replacing Maps Entirely ($patch: replace): To replace an entire map with your values (instead of merging), use `$patch: replace`. This removes all existing keys and replaces them with only your specified keys. spec: template: spec: nodeSelector: $patch: replace custom-key: custom-value 6. Replacing Lists Entirely ($patch: replace): If you want to strictly define a list and ignore all generated defaults, use `$patch: replace`. service: spec: ports: - $patch: replace - name: http port: 80 targetPort: 8080 protocol: TCP - name: https port: 443 targetPort: 8443 protocol: TCP

NamespacedObjectReference

Select the object by Name and Namespace. You can target only one object at a time.

Field	Type	Description
`name`	gwv1.ObjectName	The name of the target resource. Required.
`namespace`	*gwv1.Namespace	The namespace of the target resource. If not set, defaults to the namespace of the parent object.

ObjectMetadata

ObjectMetadata contains labels and annotations for metadata overlays.

Field	Type	Description
`labels`	map[string]string	Map of string keys and values that can be used to organize and categorize (scope and select) objects. May match selectors of replication controllers and services. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/labels
`annotations`	map[string]string	Annotations is an unstructured key value map stored with a resource that may be set by external tools to store and retrieve arbitrary metadata. They are not queryable and should be preserved when modifying objects. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations

Port

Field	Type	Description
`port`	int32	The port number to match on the Gateway Required.
`nodePort`	*int32	The NodePort to be used for the service. If not specified, a random port will be assigned by the Kubernetes API server.

Service

Configuration for a Kubernetes Service.

Field	Type	Description
`type`	*corev1.ServiceType	The Kubernetes Service type.
`clusterIP`	*string	The manually specified IP address of the service, if a randomly assigned IP is not desired. See https://kubernetes.io/docs/concepts/services-networking/service/#choosing-your-own-ip-address and https://kubernetes.io/docs/concepts/services-networking/service/#headless-services on the implications of setting `clusterIP`.
`extraLabels`	map[string]string	Additional labels to add to the Service object metadata. If the same label is present on `Gateway.spec.infrastructure.labels`, the `Gateway` takes precedence.
`extraAnnotations`	map[string]string	Additional annotations to add to the Service object metadata. If the same annotation is present on `Gateway.spec.infrastructure.annotations`, the `Gateway` takes precedence.
`ports`	[]Port	Additional configuration for the service ports. The actual port numbers are specified in the Gateway resource.
`externalTrafficPolicy`	*string	ExternalTrafficPolicy defines the external traffic policy for the service. Valid values are Cluster and Local. Default value is Cluster.
`loadBalancerClass`	*string	LoadBalancerClass is the class of the load balancer implementation this Service belongs to. If specified, the value of this field must be a label-style identifier, with an optional prefix. This field can only be set when the Service type is ‘LoadBalancer’. If not set, the default load balancer implementation is used. See https://kubernetes.io/docs/concepts/services-networking/service/#load-balancer-class
`loadBalancerSourceRanges`	[]string	LoadBalancerSourceRanges restricts traffic through the cloud-provider load-balancer to the specified client IPs. This field will be ignored if the cloud-provider does not support the feature. More info: https://kubernetes.io/docs/tasks/access-application-cluster/create-external-load-balancer/

Solo Enterprise for kgateway APIs Web Application Firewall (WAF) API

Was this page helpful?