Configuration Schemas Overview

Weik.io uses YAML configuration files to manage platform resources. Each configuration type defines a specific resource or capability through a declarative schema.

Configuration structure#

All Weik.io configurations follow this structure:

apiVersion: weik.io/v1alpha1
kind: <ConfigurationType>
metadata:
  name: resource-name
spec:
  # Configuration-specific properties

Configuration types#

API management#

Configurations for managing APIs and their lifecycle:

• Api: Define API base configuration and URL prefix
• ApiVersion: Configure API versions with authentication and connection settings
• ApiSubscription: Manage API access subscriptions
• OpenApiEndpoint: Expose OpenAPI operations as REST endpoints
• OpenApiConnector: Register OpenAPI connectors from packages

Integration#

Configurations for building integration flows:

• IntegrationFlow: Define integration flow orchestration
• IntegrationService: Create reusable integration services
• MFT: Configure managed file transfers between storage systems
• Schedule: Define scheduled tasks with cron expressions

Eventing#

Configurations for event-driven architecture:

• EventSource: Define event sources from various systems
• EventChannel: Configure event routing channels
• EventSubscription: Subscribe to events from channels
• DatabaseChangeTracking: Monitor database changes as events

Configuration and variables#

Foundational configurations:

• Variable: Define variables and secrets for use across configurations
• CoreSystem: Configure core system components (deprecated)

Common patterns#

Using variables#

Reference variables in configurations:

apiVersion: weik.io/v1alpha1
kind: Variable
metadata:
  name: database-password
spec:
  value: super-secret-password
  isSecret: true
---
apiVersion: weik.io/v1alpha1
kind: DatabaseChangeTracking
metadata:
  name: orders-tracking
spec:
  type: postgres
  parameters:
    databasePassword: "{{sys:database-password}}"

Multi-document YAML#

Define multiple resources in one file:

apiVersion: weik.io/v1alpha1
kind: EventChannel
metadata:
  name: orders-channel
spec:
  type: memory
---
apiVersion: weik.io/v1alpha1
kind: EventSource
metadata:
  name: order-webhook
spec:
  type: webhook
  eventType: com.example.orders.created
  eventSource: order-api
---
apiVersion: weik.io/v1alpha1
kind: EventSubscription
metadata:
  name: order-subscription
spec:
  source: order-webhook
  channel: orders-channel

Configuration dependencies#

Some configurations depend on others existing first:

# 1. Create API first
apiVersion: weik.io/v1alpha1
kind: Api
metadata:
  name: northwind-api
spec:
  prefix: northwind
---
# 2. Then create API version
apiVersion: weik.io/v1alpha1
kind: ApiVersion
metadata:
  name: northwind-v1
spec:
  apiName: northwind-api
  isActive: true
---
# 3. Finally create subscriptions
apiVersion: weik.io/v1alpha1
kind: ApiSubscription
metadata:
  name: customer-subscription
spec:
  apis:
    - northwind-api

Applying configurations#

Using the CLI#

Apply configurations using the CLI:

# Apply a single file
weikio config apply configuration.yaml

File organization#

Organize configurations by type or purpose:

configs/
  ├── apis/
  │   ├── api.yaml
  │   ├── api-versions.yaml
  │   └── endpoints.yaml
  ├── integrations/
  │   ├── flows.yaml
  │   ├── services.yaml
  │   └── schedules.yaml
  ├── eventing/
  │   ├── channels.yaml
  │   ├── sources.yaml
  │   └── subscriptions.yaml
  └── variables/
      ├── common.yaml
      └── secrets.yaml

Configuration best practices#

Naming conventions#

• Use lowercase with hyphens: customer-sync-flow
• Be descriptive: stripe-payment-webhook not webhook1
• Include purpose: nightly-backup-schedule
• Use consistent prefixes for related resources

Security#

• Store secrets in Variable configurations with isSecret: true
• Never commit secrets to version control
• Use environment-specific variable files
• Restrict access to configuration files
• Implement proper access controls

Version control#

• Store configurations in Git
• Use branches for environments (dev, staging, production)
• Review configuration changes through pull requests
• Tag releases for traceability
• Document breaking changes

Documentation#

• Add comments to complex configurations
• Document variable requirements
• Include example values
• Note dependencies between resources
• Maintain a configuration catalog

Testing#

• Test configurations in development first
• Validate YAML syntax before applying
• Verify resource dependencies
• Test with realistic data
• Monitor resource health after deployment

Getting help#

View configuration help:

# General help
weikio config --help

# Apply command help
weikio config apply --help

For detailed information on each configuration type, see the individual reference pages linked above.