Traefik Hub API Management Resources Conditions and Events Reference

Monitor and troubleshoot Traefik Hub API Management resources using Kubernetes Conditions and Events.

Overview

API Management resources in Traefik Hub support Kubernetes Conditions and Events, providing structured status information about your resources. Conditions are clear, actionable status indicators. They help you understand the health and state of your API Management configuration. Events provide a historical log of significant changes.

Benefits of Conditions and Events

Better visibility: Clear, structured status information instead of parsing logs
Easier troubleshooting: Identify configuration issues with specific condition types
Kubernetes-native: Follows standard Kubernetes patterns and integrations
Programmatic access: Query and monitor using kubectl or automation tools
Reduced noise: No more duplicate or transient error messages in logs
Granular status: Separate conditions for different aspects (loading vs validation, different reference types)

Design Principles

Traefik Hub's implementation follows established Kubernetes and Gateway API best practices:

Conditions

Conditions are status indicators that reflect the current observed state of a resource. Each condition represents an independent aspect of the resource's health and follows Kubernetes best practices.

Condition Structure

Each condition follows the standard metav1.Condition structure:

Field	Description
`type`	The condition type (for example, `Accepted`, `OpenAPISpecLoaded`, `APIVersionRefsResolved`)
`status`	Current status: `True`, or `False`
`reason`	Machine-readable CamelCase identifier explaining why the condition is in this state
`message`	Human-readable message with additional details
`lastTransitionTime`	Timestamp of when the condition last changed status
`observedGeneration`	The resource generation this condition reflects

Common Condition Types

These condition types appear across multiple API Management resources:

Accepted

Indicates whether the resource specification is syntactically valid and has been accepted by the system.

Status True: The resource configuration is valid and accepted
Status False: The resource has validation errors or unsuccessful dependency checks
Reason when the status is False: Inherits the reason from the blocking condition (for example, OpenAPISpecNotFound, APIPlanNotFound)

Understanding Accepted

Accepted=True indicates that the resource configuration has been validated and accepted by Traefik Hub.

However, Accepted=False can occur for two reasons:

Specification errors: The resource YAML has validation errors or missing required fields
Blocking condition problems: Certain critical conditions (like OpenAPISpecLoaded or APIPlanRefResolved) are unsuccessful, causing Accepted to propagate the problem

When Accepted=False, check both the resource specification AND other conditions to identify the root cause.

OpenAPI Specification Conditions

Resources with OpenAPI specifications (API, APIVersion) use two separate conditions for validation:

OpenAPISpecLoaded

Indicates whether the OpenAPI specification file was successfully fetched/loaded.

Status True, Reason OpenAPISpecFound: Specification file loaded successfully
Status False, Reason OpenAPISpecNotFound: Unable to fetch the specification (unreachable URL/path, network error, etc.)
Message example: "OpenAPI specification loaded successfully" or "Failed to load OpenAPI specification: {error}"

Blocks Accepted

When OpenAPISpecLoaded=False, the Accepted condition is also set to False with reason OpenAPISpecNotFound.

OpenAPISpecValidated

Indicates whether the loaded OpenAPI specification is syntactically valid.

Status True, Reason OpenAPISpecValid: Specification is valid OpenAPI/Swagger
Status False, Reason OpenAPISpecInvalid: Specification has validation errors (malformed YAML/JSON, incorrect OpenAPI schema, etc.)
Message example: "OpenAPI specification validated successfully" or "Failed to validate OpenAPI specification: {error}"

Blocks Accepted

When OpenAPISpecValidated=False, the Accepted condition is also set to False with reason OpenAPISpecInvalid.

Two-Stage Validation

OpenAPI validation is split into loading and validation stages. A spec must first be loaded (OpenAPISpecLoaded=True) before it can be validated. If loading fails, validation is skipped.

Reference Resolution Conditions

Resources that reference other resources use resource-specific conditions (not a generic ResolvedRefs):

Condition Type	Description
`APIVersionRefsResolved`	API references to APIVersions
`APIRefsResolved`	APIBundle/APICatalogItem/ManagedSubscription references to APIs
`APIBundleRefsResolved`	APICatalogItem/ManagedSubscription references to APIBundles
`APIPlanRefResolved`	APICatalogItem/ManagedSubscription references to APIPlan
`OperationSetRefsResolved`	APICatalogItem/ManagedSubscription references to operation sets
`APIPortalAuthRefResolved`	APIPortal references to APIPortalAuth
`ManagedApplicationRefsResolved`	ManagedSubscription references to ManagedApplications
`SecretRefResolved`	APIAuth/APIPortalAuth references to Secrets

Each follows the pattern:

Status True: All references resolved successfully
Status False: One or more references not found
Message: Lists the missing resource names when False

Conditions by Resource

API

Condition Type	Blocks Accepted	Description
`Accepted`	N/A	API spec is syntactically valid and accepted by the system
`OpenAPISpecLoaded`	Yes	OpenAPI specification file was successfully loaded
`OpenAPISpecValidated`	Yes	Loaded OpenAPI specification is syntactically valid
`APIVersionRefsResolved`	No	All referenced APIVersions exist and are valid
`OperationSetsValidated`	No	All operation sets defined in the spec are valid

Example Status:

{
  "type": "Accepted",
  "status": "True",
  "reason": "Accepted",
  "lastTransitionTime": "2025-11-19T10:30:00Z",
  "observedGeneration": 1
}

Common Issues:

Accepted=False: Check the reason field - it indicates which condition is unsuccessful (for example, OpenAPISpecNotFound)
APIVersionRefsResolved=False: Ensure all referenced APIVersion resources exist in the correct namespace
OpenAPISpecLoaded=False: Verify the OpenAPI spec URL/path is accessible from the Traefik Hub agent

APIVersion

Condition Type	Blocks Accepted	Description
`Accepted`	N/A	APIVersion spec is syntactically valid and accepted
`OpenAPISpecLoaded`	Yes	OpenAPI specification file was successfully loaded
`OpenAPISpecValidated`	Yes	Loaded OpenAPI specification is syntactically valid
`OperationSetsValidated`	No	All operation sets defined in the spec are valid

Example Status:

[
  {
    "type": "Accepted",
    "status": "True",
    "reason": "Accepted"
  },
  {
    "type": "OpenAPISpecLoaded",
    "status": "True",
    "reason": "OpenAPISpecFound",
    "message": "OpenAPI specification loaded successfully"
  },
  {
    "type": "OpenAPISpecValidated",
    "status": "True",
    "reason": "OpenAPISpecValid",
    "message": "OpenAPI specification validated successfully"
  }
]

Common Issues:

Accepted=False: Check the semver format of the release field, or look at other blocking conditions
OpenAPISpecValidated=False: Check that the OpenAPI spec is valid YAML/JSON and follows OpenAPI schema
OperationSetsValidated=False: Check the message field for details on which operation sets are incorrect

APIPortal

Condition Type	Blocks Accepted	Description
`Accepted`	N/A	Portal spec is syntactically valid and accepted
`APIPortalAuthRefResolved`	Yes	Referenced APIPortalAuth exists and is valid

Example Status:

[
  {
    "type": "Accepted",
    "status": "True",
    "reason": "Accepted"
  },
  {
    "type": "APIPortalAuthRefResolved",
    "status": "True",
    "reason": "APIPortalAuthFound",
    "message": "APIPortalAuth reference resolved successfully"
  }
]

Common Issues:

Accepted=False: Verify trustedUrls are valid URLs, or check if APIPortalAuthRefResolved is unsuccessful
APIPortalAuthRefResolved=False: Ensure the referenced APIPortalAuth resource exists in the namespace

APIBundle

Condition Type	Blocks Accepted	Description
`Accepted`	N/A	APIBundle spec is syntactically valid and accepted
`APIRefsResolved`	No	All referenced APIs exist and are accessible

Example Status:

[
  {
    "type": "Accepted",
    "status": "True",
    "reason": "Accepted"
  },
  {
    "type": "APIRefsResolved",
    "status": "True",
    "reason": "APIRefsFound",
    "message": "All API references resolved successfully"
  }
]

Common Issues:

APIRefsResolved=False: Check that all APIs listed in the bundle exist and are in the correct namespace. The message field lists missing APIs.

APICatalogItem

Condition Type	Blocks Accepted	Description
`Accepted`	N/A	APICatalogItem spec is syntactically valid and accepted
`APIRefsResolved`	No	All referenced APIs exist and are accessible
`APIBundleRefsResolved`	No	All referenced APIBundles exist and are accessible
`APIPlanRefResolved`	Yes	Referenced APIPlan exists and is accessible
`OperationSetRefsResolved`	No	All referenced operation sets exist in the API/APIVersion

Example Status:

[
  {
    "type": "Accepted",
    "status": "True",
    "reason": "Accepted"
  },
  {
    "type": "APIRefsResolved",
    "status": "True",
    "reason": "APIRefsFound",
    "message": "API references resolved successfully"
  },
  {
    "type": "APIBundleRefsResolved",
    "status": "True",
    "reason": "APIBundleRefsFound",
    "message": "APIBundle references resolved successfully"
  },
  {
    "type": "APIPlanRefResolved",
    "status": "True",
    "reason": "APIPlanFound",
    "message": "APIPlan reference resolved successfully"
  },
  {
    "type": "OperationSetRefsResolved",
    "status": "True",
    "reason": "OperationSetRefsFound",
    "message": "Operation set references resolved successfully"
  }
]

Common Issues:

APIPlanRefResolved=False: Verify the referenced APIPlan exists. This blocks Accepted.
APIRefsResolved=False: Check that all referenced APIs exist. The message lists missing APIs.
APIBundleRefsResolved=False: Check that all referenced APIBundles exist. The message lists missing bundles.
OperationSetRefsResolved=False: Check that the operation set names match those defined in the API's OpenAPI spec

APIPlan

Condition Type	Blocks Accepted	Description
`Accepted`	N/A	APIPlan spec is syntactically valid and accepted
`QuotaValidated`	Yes	Quota configuration is valid (only present if quota is configured)
`RateLimitValidated`	Yes	Rate limiting configuration is valid (only present if rate limit is configured)

Example Status:

[
  {
    "type": "Accepted",
    "status": "True",
    "reason": "Accepted"
  },
  {
    "type": "QuotaValidated",
    "status": "True",
    "reason": "QuotaValid",
    "message": "Quota validated successfully"
  },
  {
    "type": "RateLimitValidated",
    "status": "True",
    "reason": "RateLimitValid",
    "message": "Rate limit validated successfully"
  }
]

Common Issues:

QuotaValidated=False: Check the quota configuration and verify Redis connectivity (if using Redis-based quota)
RateLimitValidated=False: Verify rate limit values are valid and Redis is available (if using Redis-based rate limiting)

Conditional Conditions

QuotaValidated and RateLimitValidated only appear in the status if quota or rate limit is configured in the spec. If neither is configured, only Accepted will be present.

ManagedSubscription

Condition Type	Blocks Accepted	Description
`Accepted`	N/A	ManagedSubscription spec is syntactically valid and accepted
`APIRefsResolved`	No	All referenced APIs exist
`APIBundleRefsResolved`	No	All referenced APIBundles exist
`APIPlanRefResolved`	Yes	Referenced APIPlan exists
`ManagedApplicationRefsResolved`	No	All referenced ManagedApplications exist
`OperationSetRefsResolved`	No	All referenced operation sets exist
`ClaimValidated`	Yes	JWT claim configuration is valid

Example Status:

[
  {
    "type": "Accepted",
    "status": "True",
    "reason": "Accepted"
  },
  {
    "type": "APIRefsResolved",
    "status": "True",
    "reason": "APIRefsFound",
    "message": "API references resolved successfully"
  },
  {
    "type": "APIPlanRefResolved",
    "status": "True",
    "reason": "APIPlanFound",
    "message": "APIPlan reference resolved successfully"
  },
  {
    "type": "ManagedApplicationRefsResolved",
    "status": "True",
    "reason": "ManagedApplicationRefsFound",
    "message": "ManagedApplication references resolved successfully"
  },
  {
    "type": "ClaimValidated",
    "status": "True",
    "reason": "ClaimValid",
    "message": "Claim validated successfully"
  }
]

Common Issues:

APIPlanRefResolved=False: Ensure the ManagedSubscription references a valid APIPlan. This blocks Accepted.
ManagedApplicationRefsResolved=False: Verify all referenced ManagedApplications exist. The message lists missing applications.
APIRefsResolved=False: Check that all referenced APIs exist
ClaimValidated=False: Check the JWT claim configuration. This blocks Accepted.

Blocking vs Informational Conditions

Understanding which conditions block Accepted is critical for troubleshooting:

Conditions That Block Accepted

When these conditions are False, the Accepted condition is also set to False with the same reason:

Resource	Blocking Conditions
API	`OpenAPISpecLoaded`, `OpenAPISpecValidated`
APIVersion	`OpenAPISpecLoaded`, `OpenAPISpecValidated`
APIPortal	`APIPortalAuthRefResolved`
APICatalogItem	`APIPlanRefResolved`
APIPlan	`QuotaValidated`, `RateLimitValidated`
ManagedSubscription	`APIPlanRefResolved`, `ClaimValidated`

Example of blocking:

[
  {
    "type": "Accepted",
    "status": "False",
    "reason": "OpenAPISpecNotFound"
  },
  {
    "type": "OpenAPISpecLoaded",
    "status": "False",
    "reason": "OpenAPISpecNotFound",
    "message": "Failed to load OpenAPI specification: connection refused"
  }
]

Notice how Accepted inherits the reason from the unsuccessful OpenAPISpecLoaded condition.

Informational Conditions

These conditions provide status information but do NOT block Accepted:

Condition Type	Resources	Purpose
`APIVersionRefsResolved`	API	Informational about APIVersion references
`OperationSetsValidated`	API, APIVersion	Informational about operation set validity
`APIRefsResolved`	APIBundle, APICatalogItem, ManagedSubscription	Informational about API references
`APIBundleRefsResolved`	APICatalogItem, ManagedSubscription	Informational about bundle references
`ManagedApplicationRefsResolved`	ManagedSubscription	Informational about application references
`OperationSetRefsResolved`	APICatalogItem, ManagedSubscription	Informational about operation set references

Example of informational condition:

[
  {
    "type": "Accepted",
    "status": "True",
    "reason": "Accepted"
  },
  {
    "type": "APIVersionRefsResolved",
    "status": "False",
    "reason": "APIVersionRefsNotFound",
    "message": "Failed to resolve APIVersion references: v2-beta, v3-alpha"
  }
]

Here, Accepted=True even though APIVersionRefsResolved=False. This allows the API to be accepted while warning about missing versions.

Events

Events are informational messages generated when significant state changes occur. They provide a historical log of what has happened to your resources, useful for troubleshooting and auditing.

Currently, Traefik Hub generates Kubernetes Events for OpenAPI specification updates. Events appear in the Kubernetes event stream and can be viewed with kubectl get events or kubectl describe.

OpenAPI Specification Events

These events are generated for resources with OpenAPI specifications (API, APIVersion):

OpenAPISpecUpdated

Field	Value
Type	Normal
Reason	`OpenAPISpecUpdated`
Message	`OpenAPI specification has been updated`

When triggered:

The OpenAPI specification is successfully fetched
The fetched specification content differs from the previously cached version
The specification passes validation

Example:

Type:    Normal
Reason:  OpenAPISpecUpdated
Message: OpenAPI specification has been updated

OpenAPISpecInvalid

Field	Value
Type	Warning
Reason	`OpenAPISpecInvalid`
Message	Variable error message describing the specific error

When triggered:

Unable to fetch the specification from the source (URL, Service path)
Specification unmarshaling fails
Specification validation fails (incorrect OpenAPI v2 or v3 format)
Unrecognized OpenAPI specification version

Error message patterns:

Loading errors - Prefixed with loading OpenAPI specification:
- Unable to fetch from URL or Service path
- Network errors when fetching from a service endpoint
Validation errors - Prefixed with validating OpenAPI specification:
- Unmarshaling failures
- Incorrect OpenAPI v2 or v3 structure
- Conversion errors from v2 to v3
- Schema validation failures
- Unrecognized OpenAPI version

Example:

Type:    Warning
Reason:  OpenAPISpecInvalid
Message: loading OpenAPI specification: failed to fetch from http://backend-service/openapi.json: connection refused

Viewing Events

The easiest way to view events for a resource is using kubectl describe:

kubectl describe api <api-name> -n <namespace>

The events will appear at the bottom of the output:

Events:
  Type    Reason                 Age   From                Message
  ----    ------                 ----  ----                -------
  Normal  OpenAPISpecUpdated     2m    traefik-hub-agent   OpenAPI specification has been updated
  Warning OpenAPISpecInvalid     5m    traefik-hub-agent   loading OpenAPI specification: connection refused

You can also view events directly using kubectl get events:

kubectl get events --field-selector involvedObject.name=<resource-name> -n <namespace>

For example, to see events for an API named weather-api:

kubectl get events --field-selector involvedObject.name=weather-api -n apps

To watch for events in real-time across a namespace:

kubectl get events --watch -n <namespace>

To see only warning events:

kubectl get events --field-selector type=Warning -n <namespace>

Monitoring and Troubleshooting

Viewing Conditions

To view the conditions for a resource, use kubectl describe:

kubectl describe <resource-type> <resource-name> -n <namespace>

For example:

kubectl describe api weather-api -n apps

The conditions will appear in the status section of the output:

Status:
  Conditions:
    Last Transition Time:  2025-11-19T10:30:00Z
    Message:
    Observed Generation:   1
    Reason:                Accepted
    Status:                True
    Type:                  Accepted
    Last Transition Time:  2025-11-19T10:30:01Z
    Message:               Quota validated successfully
    Observed Generation:   1
    Reason:                QuotaValid
    Status:                True
    Type:                  QuotaValidated
    Last Transition Time:  2025-11-19T10:30:01Z
    Message:               Rate limit validated successfully
    Observed Generation:   1
    Reason:                RateLimitValid
    Status:                True
    Type:                  RateLimitValidated

You can also get the conditions in JSON format:

kubectl get api <api-name> -n <namespace> -o jsonpath='{.status.conditions}' | jq

Example JSON output:

[
  {
    "type": "Accepted",
    "status": "True",
    "reason": "Accepted",
    "lastTransitionTime": "2025-11-19T10:30:00Z",
    "observedGeneration": 1
  },
  {
    "type": "OpenAPISpecLoaded",
    "status": "True",
    "reason": "OpenAPISpecFound",
    "message": "OpenAPI specification loaded successfully",
    "lastTransitionTime": "2025-11-19T10:30:05Z",
    "observedGeneration": 1
  }
]

Filtering Specific Conditions

To check a specific condition:

kubectl get api <api-name> -n <namespace> -o jsonpath='{.status.conditions[?(@.type=="OpenAPISpecLoaded")]}'

To list all resources with Accepted=False:

kubectl get api -A -o json | jq -r '.items[] | select(.status.conditions[]? | select(.type=="Accepted" and .status=="False")) | "\(.metadata.namespace)/\(.metadata.name)"'

Common Troubleshooting Scenarios

Scenario 1: API Not Accepting Traffic

Symptom: Your API is configured but not receiving traffic.

Diagnosis:

kubectl describe api <api-name> -n <namespace>

Check:

Accepted condition: Should be True
- If False: Check the reason field to see which blocking condition is unsuccessful
APIVersionRefsResolved condition: Check if all versions exist
- If False: Check that all APIVersion resources exist (this is informational but may indicate config issues)

Scenario 2: OpenAPI Specification Not Loading

Symptom: API Portal doesn't show your API documentation.

Diagnosis:

kubectl get api <api-name> -n <namespace> -o jsonpath='{.status.conditions[?(@.type=="OpenAPISpecLoaded")]}' | jq

If OpenAPISpecLoaded = False:

Check the message field for the specific error:

kubectl get api <api-name> -n <namespace> -o jsonpath='{.status.conditions[?(@.type=="OpenAPISpecLoaded")].message}'

Check recent events for details:

kubectl get events --field-selector involvedObject.name=<api-name>,reason=OpenAPISpecInvalid -n <namespace>

Verify the OpenAPI spec path/URL is accessible from the Traefik Hub agent pod
Check network connectivity and firewall rules

If OpenAPISpecLoaded = True but OpenAPISpecValidated = False:

The spec file was fetched but is not valid

Check the validation error message:

kubectl get api <api-name> -n <namespace> -o jsonpath='{.status.conditions[?(@.type=="OpenAPISpecValidated")].message}'

Validate your OpenAPI document using tools like Swagger Editor

Scenario 3: APICatalogItem Not Working

Symptom: Catalog items aren't appearing in the portal.

Diagnosis:

kubectl describe apicatalogitem <catalog-item-name> -n <namespace>

Check all reference conditions:

APIPlanRefResolved: Must be True (blocks Accepted if False)
APIRefsResolved: Verify all referenced APIs exist
APIBundleRefsResolved: Verify APIBundle exists (if used)
OperationSetRefsResolved: Verify operation set names match the API's OpenAPI spec

Quick verification:

# Check if plan exists
kubectl get apiplan <plan-name> -n <namespace>

# Check if APIs exist
kubectl get api -n <namespace>

# Check if bundles exist
kubectl get apibundle -n <namespace>

Scenario 4: Understanding Eventual Consistency

Symptom: Conditions show False temporarily, then become True.

Explanation: Traefik Hub uses an eventually consistent model. Due to dependencies between resources and Kubernetes reconciliation loops, resources may temporarily show errors while the system converges.

Example Timeline:

t=0s: You create an API with references to APIVersions
t=1s: API condition APIVersionRefsResolved=False (APIVersions not created yet)
t=5s: APIVersions are created and processed
t=6s: API condition APIVersionRefsResolved=True (system converged)

Best Practice: Wait 10-30 seconds after creating resources before investigating False conditions. Monitor lastTransitionTime to see the progression of state changes.

Scenario 5: Accepted is False but Spec Looks Correct

Symptom: Your resource YAML is valid, but Accepted=False.

Cause: Accepted=False can be caused by blocking condition problems, not only spec errors.

Diagnosis:

Check the reason field of the Accepted condition:

kubectl get api <api-name> -n <namespace> -o jsonpath='{.status.conditions[?(@.type=="Accepted")]}'

Look for the condition with the same reason:

kubectl get api <api-name> -n <namespace> -o jsonpath='{.status.conditions}' | jq '.[] | select(.status=="False")'

Example:

{
  "type": "Accepted",
  "status": "False",
  "reason": "APIPlanNotFound"
}

This indicates that APIPlanRefResolved is unsuccessful, blocking acceptance.

Important: Reference resolution checks BOTH existence and acceptance of the referenced resource. A resource reference will show "NotFound" in two cases:

The resource doesn't exist in Kubernetes
The resource exists but has Accepted=False (is not accepted due to validation problems)

Example: If an APICatalogItem references an APIPlan, but the APIPlan has Accepted=False because it uses rate limiting without Redis connectivity, the APICatalogItem will show APIPlanNotFound even though the APIPlan resource exists in the cluster.

To fix: Check if the referenced resource exists AND is accepted:

# Check if the resource exists
kubectl get apiplan <plan-name> -n <namespace>

# Check if it's accepted
kubectl get apiplan <plan-name> -n <namespace> -o jsonpath='{.status.conditions[?(@.type=="Accepted")]}'

If the resource exists but is not accepted, fix the underlying problem preventing acceptance (check other conditions for details).

Common Patterns

Pattern 1: All Resources Have Accepted

Every API Management resource implements the Accepted condition. This is the first condition to check when troubleshooting - if Accepted is False, check:

The reason field to identify the root cause
Other conditions with status=False to see what's blocking acceptance
The resource spec for validation errors

Pattern 2: Two-Stage OpenAPI Validation

API and APIVersion resources validate OpenAPI specifications in two stages:

Loading (OpenAPISpecLoaded): Can the file be fetched?
Validation (OpenAPISpecValidated): Is the content valid?

Both must be True for the OpenAPI spec to be considered valid. If loading fails, validation is skipped.

Pattern 3: Resource-Specific Reference Conditions

Unlike generic ResolvedRefs, Traefik Hub uses specific conditions per reference type:

This provides granular visibility into which references are missing
Message fields list the specific missing resources by name
Allows distinguishing between different types of missing references

Pattern 4: Condition Convergence

Resources with dependencies may show temporary False conditions while the system converges:

Time  0s:  Accepted=True, OpenAPISpecLoaded=Unknown, APIVersionRefsResolved=Unknown
Time  5s:  Accepted=True, OpenAPISpecLoaded=True, APIVersionRefsResolved=True

This is expected behavior. Monitor the lastTransitionTime to see progression.

Pattern 5: Blocking vs Informational

Not all False conditions block Accepted. Understanding this distinction is critical:

Blocking (for example, OpenAPISpecLoaded, APIPlanRefResolved): Must be True for Accepted=True
Informational (for example, APIVersionRefsResolved, OperationSetsValidated): Can be False while Accepted=True

Integration with Monitoring Tools

Prometheus Metrics

You can expose condition states as Prometheus metrics using tools like kube-state-metrics:

# Example metric
kube_customresource_api_accepted{
  customresource_kind="API",
  customresource_name="weather-api",
  customresource_namespace="apps",
  condition="Accepted",
  status="true"
} 1

OpenTelemetry

You can also collect condition states using the OpenTelemetry Collector with the Kubernetes Objects Receiver:

receivers:
  k8sobjects:
    objects:
      - name: apis
        mode: watch
        group: hub.traefik.io
        namespaces: [default, production]

processors:
  attributes:
    actions:
      - key: k8s.resource.type
        value: api
        action: insert
      - key: condition.type
        from_attribute: status.conditions[*].type
        action: extract
      - key: condition.status
        from_attribute: status.conditions[*].status
        action: extract

exporters:
  otlp:
    endpoint: otel-collector:4317

This allows you to monitor conditions in your OpenTelemetry-based observability stack and create dashboards in tools like Grafana or Jaeger.

Alerting

Create alerts based on condition states:

# Example Prometheus alert rule
- alert: APINotAccepted
  expr: |
    kube_customresource_condition{
      customresource_kind="API",
      condition="Accepted",
      status="false"
    } > 0
  for: 5m
  annotations:
    summary: "API {{ $labels.customresource_name }} not accepted"
    description: "API {{ $labels.customresource_name }} in namespace {{ $labels.customresource_namespace }} has been in an unaccepted state for 5 minutes. Check conditions for details."

- alert: OpenAPISpecNotLoaded
  expr: |
    kube_customresource_condition{
      customresource_kind="API",
      condition="OpenAPISpecLoaded",
      status="false"
    } > 0
  for: 2m
  annotations:
    summary: "API {{ $labels.customresource_name }} OpenAPI spec not loaded"
    description: "Failed to load OpenAPI spec for API {{ $labels.customresource_name }}. Check network connectivity and spec URL."

Overview​

Benefits of Conditions and Events​

Design Principles​

Conditions​

Condition Structure​

Common Condition Types​

Accepted​

OpenAPI Specification Conditions​

OpenAPISpecLoaded​

OpenAPISpecValidated​

Reference Resolution Conditions​

Conditions by Resource​

API​

APIVersion​

APIPortal​

APIBundle​

APICatalogItem​

APIPlan​

ManagedSubscription​

Blocking vs Informational Conditions​

Conditions That Block Accepted​

Informational Conditions​

Events​

OpenAPI Specification Events​

OpenAPISpecUpdated​

OpenAPISpecInvalid​

Viewing Events​

Monitoring and Troubleshooting​

Viewing Conditions​

Filtering Specific Conditions​

Common Troubleshooting Scenarios​

Common Patterns​

Integration with Monitoring Tools​

Prometheus Metrics​

OpenTelemetry​

Alerting​

Related Content​

Overview

Benefits of Conditions and Events

Design Principles

Conditions

Condition Structure

Common Condition Types

Accepted

OpenAPI Specification Conditions

OpenAPISpecLoaded

OpenAPISpecValidated

Reference Resolution Conditions

Conditions by Resource

API

APIVersion

APIPortal

APIBundle

APICatalogItem

APIPlan

ManagedSubscription

Blocking vs Informational Conditions

Conditions That Block Accepted

Informational Conditions

Events

OpenAPI Specification Events

OpenAPISpecUpdated

OpenAPISpecInvalid

Viewing Events

Monitoring and Troubleshooting

Viewing Conditions

Filtering Specific Conditions

Common Troubleshooting Scenarios

Common Patterns

Integration with Monitoring Tools

Prometheus Metrics

OpenTelemetry

Alerting

Related Content