Skip to content

api-reference.md

Latest commit

 

History

History
457 lines (243 loc) · 21.1 KB

api-reference.md

File metadata and controls

457 lines (243 loc) · 21.1 KB
Raw

API Reference

Packages

exploitiq.openshift.io/v1alpha1

Package v1alpha1 contains API Schema definitions for the exploitiq v1alpha1 API group.

Resource Types

AuthSpec

AuthSpec defines the configuration for the authentication component.

Appears in:

Field Description Default Validation
oidc OIDCSpec OIDC configuration for Kubernetes

CacheSpec

CacheSpec defines the configuration for the Cache component.

Appears in:

Field Description Default Validation
deployment DeploymentSpec Optional: {}
container ContainerSpec Optional: {}

ContainerSpec

ContainerSpec defines the common configuration for a single container.

Appears in:

Field Description Default Validation
image string Image is the container image to use. Optional: {}
imagePullPolicy PullPolicy ImagePullPolicy controls when the image is pulled.
Defaults to Always if :latest tag is specified, or IfNotPresent otherwise.		 Enum: [Always Never IfNotPresent]
Optional: {}
resources ResourceRequirements Resources defines the compute resources required by this container. Optional: {}
extraEnv EnvVar array ExtraEnv specifies additional environment variables that will override
default variables from ConfigMap/envFrom. Variables specified here
take precedence over those loaded from ConfigMap.		 Optional: {}

DatabaseMode

Underlying type: string

DatabaseMode defines the MongoDB connection mode.

Appears in:

Field Description
hostPort DatabaseModeHostPort connects via host:port and discrete credentials.
Secret must contain keys: host, username, password.
connectionString DatabaseModeConnectionString connects via a full MongoDB connection string.
Secret must contain key: connection-string.
Use for Atlas, DocumentDB, or any SRV-based managed MongoDB.

DatabaseSpec

DatabaseSpec configures the external MongoDB connection for the WebApp.

Appears in:

Field Description Default Validation
mode DatabaseMode Mode selects the MongoDB connection mode.
hostPort: reads host, username, password from secretRef.
connectionString: reads connection-string from secretRef.		 hostPort Enum: [hostPort connectionString]
Optional: {}
secretRef LocalObjectReference SecretRef references a Secret containing MongoDB connection parameters.
For mode=hostPort the Secret must contain:
host — MongoDB host:port (e.g. "mymongo.example.com:27017")
username — application username
password — application password
For mode=connectionString the Secret must contain:
connection-string — full MongoDB URI (e.g. "mongodb+srv://user:pass@cluster/")
Defaults to Secret named "mongodb-credentials" when not set (backward compatibility).		 Optional: {}
database string Database is the MongoDB database name. exploit-iq-client Optional: {}
authSource string AuthSource is the authentication source database.
Defaults to the value of Database when not set.		 Optional: {}
tls MongoDBTLSSpec TLS configures optional TLS for the MongoDB connection. Optional: {}

DeploymentSpec

DeploymentSpec defines the common deployment configuration.

Appears in:

Field Description Default Validation
replicas integer Number of desired pods. Defaults to 1. 1 Minimum: 0
Optional: {}

EmbeddingSpec

EmbeddingSpec defines the configuration for the text embedding model connection.

The engine always reaches the embedder through the cache's nim_embed route, so only the upstream endpoint and model identity are configurable here. Leave BaseURL empty to fall back to the NVIDIA-hosted embedding endpoint (the prior default); set it to a self-hosted embedding NIM to keep embeddings in-cluster.

Appears in:

Field Description Default Validation
baseURL string BaseURL is the upstream endpoint the cache proxies embedding requests to
(NGINX_UPSTREAM_NIM_EMBED). Defaults to NVIDIA Cloud if empty.		 Optional: {}
Pattern: ^https?://[a-zA-Z0-9][-a-zA-Z0-9.]*[a-zA-Z0-9](:[0-9]+)?(/.*)?$
modelName string ModelName is the identifier of the embedding model served at BaseURL
(e.g. "nvidia/nv-embedqa-e5-v5"). Maps to the engine's EMBEDDER_MODEL_NAME.
When empty, the engine's built-in default model is used.		 Optional: {}
authSecretRef SecretKeySelector AuthSecretRef points to a Secret key holding the API key for the embedding
upstream. Maps to NVIDIA_API_KEY in the nginx-cache init container, which
controls the Authorization header rewrite for the /nim_embed route.
Set this when embedding.baseURL points to an auth-requiring endpoint (e.g. the
NVIDIA-hosted embedding API) while llm.mode is 'openai'. When unset, behavior
is unchanged: 'openai' mode sends no embedding key, 'nim' mode uses
exploit-iq-secret.nvidia_api_key.

EnginePVCSpec

EnginePVCSpec defines PVC configuration for Engine storage volumes.

Appears in:

Field Description Default Validation
size string Size specifies the storage size. Optional: {}
storageClass string StorageClass specifies the storage class. Uses cluster default when not set. Optional: {}

EngineSpec

EngineSpec defines the configuration for the Engine component.

Appears in:

Field Description Default Validation
deployment DeploymentSpec Optional: {}
mainContainer ContainerSpec Optional: {}
tracingContainer TracingSpec Optional: {}
pullSecretRef LocalObjectReference PullSecretRef references a Secret for pulling images from private registries.
Optional when using public images (e.g. quay.io/ecosystem-appeng/).		 Optional: {}
customConfigMapRef LocalObjectReference CustomConfigMapRef allows the user to define their own configuration ConfigMap. Optional: {}
imageRegistryCredentialsSecretRef LocalObjectReference ImageRegistryCredentialsSecretRef references a docker-config Secret for runtime image registry access.
Mounted at /tmp/.docker as config.json.		 Optional: {}
gitCaBundleConfigMapRef LocalObjectReference GitCaBundleConfigMapRef references a ConfigMap containing a custom CA bundle for Git operations.
Mounted at /app/git-ca-bundle.		 Optional: {}
tracingRouteEnabled boolean TracingRouteEnabled controls whether to create the tracing Route on OpenShift. false Optional: {}
dataPVC EnginePVCSpec DataPVC configures the PVC for Engine working data (exploit-iq-data). { size:20Gi } Optional: {}
packageCachePVC EnginePVCSpec PackageCachePVC configures the PVC for the Go/package cache (exploit-iq-package-cache). { size:50Gi } Optional: {}

ExploitIQStack

ExploitIQStack is the Schema for the exploitiqstacks API.

Field Description Default Validation
apiVersion string exploitiq.openshift.io/v1alpha1
kind string ExploitIQStack
metadata ObjectMeta Refer to Kubernetes API documentation for fields of metadata.
spec ExploitIQStackSpec
status ExploitIQStackStatus

ExploitIQStackSpec

ExploitIQStackSpec defines the desired state of ExploitIQStack.

Appears in:

Field Description Default Validation
auth AuthSpec Auth defines the configuration for the authentication component. Optional: {}
managed boolean Managed controls whether the operator manages this resource.
When set to false, the operator will not reconcile this resource.		 true Optional: {}
llm LLMSpec LLM defines the configuration for the Large Language Model connection. { mode:nim } Optional: {}
embedding EmbeddingSpec Embedding defines the configuration for the text embedding model connection. Optional: {}
platform PlatformSpec Platform-specific configuration Optional: {}
engine EngineSpec Engine component configuration
webApp WebAppSpec WebApp component configuration
cache CacheSpec Cache component configuration
database DatabaseSpec Database component configuration

ExploitIQStackStatus

ExploitIQStackStatus defines the observed state of ExploitIQStack.

Appears in:

Field Description Default Validation
conditions Condition array Conditions store the status conditions of the ExploitIQ stack status

GatewayReference

GatewayReference references a Gateway resource.

Appears in:

Field Description Default Validation
name string Name of the Gateway Required: {}
namespace string Namespace of the Gateway Optional: {}

IngressMode

Underlying type: string

IngressMode defines how external access is configured.

Appears in:

Field Description
auto IngressModeAuto is the default mode.
OpenShift behaves like managed; Kubernetes behaves like headless.
managed IngressModeManaged means the operator creates Route/Ingress/HTTPRoute.
headless IngressModeHeadless means the operator creates no external network resources.

IngressSpec

IngressSpec defines external access configuration.

Appears in:

Field Description Default Validation
baseDomain string BaseDomain is the base DNS suffix for all generated hostnames.
Optional on OpenShift (auto-discovered), required when mode == managed on Kubernetes.		 Optional: {}
mode IngressMode Mode controls how external access is configured.
auto: OpenShift behaves like managed; Kubernetes behaves like headless.
managed: Operator creates Route/Ingress/HTTPRoute.
headless: Operator creates no external network resources.		 auto Enum: [auto managed headless]
Optional: {}
gatewayRef GatewayReference GatewayRef references a Gateway for HTTPRoute creation (Kubernetes only). Optional: {}
ingressClassName string IngressClassName specifies the Ingress class to use (Kubernetes only). Optional: {}

LLMMode

Underlying type: string

LLMMode defines the interaction protocol for LLM.

Appears in:

Field Description
nim LLMModeNIM uses the NVIDIA NIM microservices specific path and defaults.
openai LLMModeOpenAI uses standard OpenAI-compatible API (self-hosted or external).

LLMSpec

LLMSpec defines the configuration for the LLM connection.

Appears in:

Field Description Default Validation
mode LLMMode Mode defines the interaction protocol.
'nim' uses the NVIDIA NIM microservices specific path and defaults.
'openai' uses standard OpenAI-compatible API (self-hosted or external).		 nim Enum: [nim openai]
Optional: {}
baseURL string BaseURL is the endpoint for the LLM service.
Defaults to NVIDIA Cloud if empty and mode is 'nim'.
Required if mode is 'openai'.		 Optional: {}
Pattern: ^https?://[a-zA-Z0-9][-a-zA-Z0-9.]*[a-zA-Z0-9](:[0-9]+)?(/.*)?$
modelName string ModelName is the identifier of the model (e.g. "meta-llama/Meta-Llama-3-8B-Instruct").
Required if mode is 'openai'.		 Optional: {}
authSecretRef SecretKeySelector AuthSecretRef allows pointing to a Secret containing the API Key.
For 'nim' mode, this maps to NVIDIA_API_KEY.
For 'openai' mode, this maps to OPENAI_API_KEY.

MongoDBTLSSpec

MongoDBTLSSpec defines TLS settings for MongoDB connections.

Appears in:

Field Description Default Validation
enabled boolean Enabled enables TLS for the MongoDB connection. false Optional: {}
configurationName string ConfigurationName is a named TLS configuration in the Quarkus TLS registry.
Required when using a custom CA or self-signed certificate.		 Optional: {}
trustStorePEMConfigMapRef LocalObjectReference TrustStorePEMConfigMapRef references a ConfigMap containing the CA certificate.
The ConfigMap must have a key named "ca.crt" containing the PEM-encoded certificate.
Required when ConfigurationName is set.		 Optional: {}

OIDCProvider

Underlying type: string

OIDCProvider identifies the OIDC identity provider. The webapp performs generic OIDC discovery and does not need this, but the engine requires a provider-specific machine-to-machine token flow for its callbacks, so the provider must be explicit.

Validation:

  • Enum: [keycloak cognito]

Appears in:

Field Description
keycloak OIDCProviderKeycloak selects the Keycloak token flow for engine callbacks.
cognito OIDCProviderCognito selects the AWS Cognito token flow for engine callbacks.

OIDCSpec

OIDCSpec defines the configuration for the OIDC authentication.

Appears in:

Field Description Default Validation
clientID string ClientID is the OIDC client identifier registered with the identity provider.
For Cognito this is the UI app client used for browser login; the engine's
machine-to-machine callbacks use engineClientID when set.
clientSecretRef SecretKeySelector ClientSecretRef references a Secret key containing the OIDC client secret.
issuerURL string IssuerURL is the base URL of the OIDC identity provider (e.g. "https://accounts.google.com").
provider OIDCProvider Provider identifies the OIDC identity provider so the engine selects the correct
machine-to-machine token flow for its callbacks to the webapp. Defaults to keycloak.		 keycloak Enum: [keycloak cognito]
cognitoDomain string CognitoDomain is the AWS Cognito domain used for the engine's machine-to-machine
token flow (e.g. "https://myapp.auth.us-east-1.amazoncognito.com"). Required when
provider is cognito; it cannot be derived reliably from issuerURL.
cognitoScope string CognitoScope is the custom OAuth2 scope for Cognito M2M authentication
(e.g. "exploitiq-resource-server/exploitiq-api-access"). Required when provider is
cognito: the engine requests it in the client_credentials grant and the webapp maps
it to the exploitiq-api-access role to accept the engine callback.
engineClientID string EngineClientID is the Cognito M2M app client identifier used for the engine's
machine-to-machine callbacks to the webapp (OAuth2 client_credentials grant).
When unset, the engine reuses ClientID. Set this to use a dedicated M2M app client
separate from the UI app client, matching the two-client Cognito topology.
engineClientSecretRef SecretKeySelector EngineClientSecretRef references a Secret key with the Cognito M2M app client secret
paired with engineClientID. When unset, the engine reuses ClientSecretRef.

PlatformSpec

PlatformSpec defines platform-specific configuration.

Appears in:

Field Description Default Validation
ingress IngressSpec Ingress configuration for external access Optional: {}

TracingSpec

TracingSpec defines the configuration for the tracing sidecar container.

Appears in:

Field Description Default Validation
enabled boolean Enabled controls whether the tracing container is enabled. true Optional: {}
container ContainerSpec Container defines the tracing container configuration. Optional: {}

WebAppSpec

WebAppSpec defines the configuration for the WebApp component.

Appears in:

Field Description Default Validation
deployment DeploymentSpec Optional: {}
container ContainerSpec Optional: {}
registryCredentialsSecretRef LocalObjectReference Required: {}
oauthClientSecretRef LocalObjectReference OAuthClientSecretRef is optional - if not provided, a secret will be generated Optional: {}
routeEnabled boolean RouteEnabled controls whether to create the main WebApp Route on OpenShift. true Optional: {}
swaggerUIRouteEnabled boolean SwaggerUIRouteEnabled controls whether to create the Swagger UI Route on OpenShift. false Optional: {}
oidcCaBundleConfigMapRef LocalObjectReference OIDCCaBundleConfigMapRef references a ConfigMap containing the OIDC provider CA certificate.
The ConfigMap must have a key named "ca-bundle.crt" with a PEM-encoded certificate.
When set, the operator mounts the ConfigMap into both the WebApp pod (configuring Quarkus
OIDC to trust the CA) and the Engine pod (VERIFY_PATH_KEYCLOAK, so the engine trusts the CA
when acquiring a Keycloak token for engine->webapp callbacks).
Use this when the OpenShift OAuth or OIDC provider uses a custom CA that the components do not trust by default.		 Optional: {}