types.JobSpec
config object
Config contains type-specific configuration for the workload. The structure depends on the job type (e.g., pipeline config, query parameters).
Config contains type-specific configuration for the workload. The structure depends on the job type (e.g., pipeline config, query parameters).
Description is an optional human-readable description of the job.
labels object
Labels is used to associate arbitrary labels with this job. Labels can be used for filtering and selection.
meta object
Meta is used to associate arbitrary metadata with this job. Keys with the prefix "expanso.io/" are reserved for system use.
Name is the logical name of the job used to refer to it. Submitting a job with the same name as an existing job will result in an update to the existing job.
Namespace is the namespace this job is running in.
Priority defines the scheduling priority of this job. Higher values indicate higher priority.
RestartPolicy controls restart behavior when executions exit.
- "on-failure" (default): Restart on non-zero exit, complete on success
- "always": Restart on any exit (current daemon behavior)
- "never": No restart, one-shot execution
rollout object
Rollout defines how to rollout the job
Auto-promote canary rollouts
Canary-specific settings
Percentage of canary nodes
health_check object
HealthCheck defines health check configuration (required for rolling/canary, ignored for immediate)
Deadline is the maximum time to wait for an execution to become healthy (required)
Possible values: [-9223372036854776000, 9223372036854776000, 1, 1000, 1000000, 1000000000, 60000000000, 3600000000000, 3600000000000, 10000000000]
FailureThreshold is the number of consecutive unhealthy intervals before the execution is considered unhealthy (optional, default: 3)
Interval is the duration of each health evaluation window (optional, default: 10s) Error rate is calculated per interval, not lifetime.
Possible values: [-9223372036854776000, 9223372036854776000, 1, 1000, 1000000, 1000000000, 60000000000, 3600000000000, 3600000000000, 10000000000]
MaxErrorRate is the maximum error rate allowed during health checks (optional, default: 0.10) Pointer because we need to distinguish nil (use default) from explicit 0.0
SuccessThreshold is the number of consecutive healthy intervals before the execution is considered healthy (optional, default: 2)
MaxFailedNodes is the maximum number of failed nodes before stopping (optional, default: 10)
MaxFailedNodesPercent is the maximum percentage of failed nodes before stopping (optional, default: 10.0)
MaxParallel is the maximum percentage of nodes to update in parallel (0-100) For immediate strategy: this value is ignored (all nodes updated simultaneously) For rolling/canary: controls wave size as percentage of total nodes (default: 10 if not specified) Examples: 10 = 10% of nodes per wave, 50 = 50% of nodes per wave, 100 = all nodes at once
NoAutoRollback disables automatic rollback on rollout failure (default: false = auto-rollback enabled)
Strategy: immediate|rolling|canary
Possible values: [immediate, rolling, canary]
secret_providers object
SecretProviders declares named secret provider backends. Keys are user-chosen identifiers that secrets reference via their From field.
property name* types.SecretProviderSpec
Address is the Vault server URL (required for hashicorp_vault).
auth object
Auth defines how to authenticate to this provider. Optional for cloud providers (SDK default chain), required for hashicorp_vault.
AccessKeyID is a static AWS access key ID.
ClientID is the Azure AD application (client) ID.
ClientSecretEnv is the environment variable containing the Azure client secret.
ImpersonateServiceAccount is the target service account to impersonate.
JWT is the JWT token value.
JWTEnv is the environment variable containing the JWT token.
JWTFile is the path to a file containing the JWT token.
ManagedIdentityClientID is the client ID for a user-assigned managed identity.
Method is the authentication method.
MountPath overrides the default auth mount path in Vault (e.g. "auth/approle").
Path is the path to a credential file for file-based auth.
Role is the backend role name (Vault role, AWS role, etc.) bound to the identity.
RoleID is the AppRole role ID value.
RoleIDEnv is the environment variable containing the AppRole role ID.
RoleIDFile is the path to a file containing the AppRole role ID.
SecretAccessKey is a static AWS secret access key.
SecretID is the AppRole secret ID value.
SecretIDEnv is the environment variable containing the AppRole secret ID.
SecretIDFile is the path to a file containing the AppRole secret ID.
ServiceAccountKeyFile is the path to a GCP service account key JSON file.
TenantID is the Azure AD tenant ID.
Token is a static Vault token value.
TokenEnv is the environment variable containing a static Vault token.
TokenFile is the path to the projected service account token. Default: /var/run/secrets/kubernetes.io/serviceaccount/token
DurationSeconds is the STS session duration (default: 3600, max: 43200).
EndpointURL is a custom endpoint (LocalStack, PrivateLink, VPC endpoints).
ExternalID is for sts:ExternalId trust policies.
Location is the GCP location for regional secrets.
Namespace is the Vault Enterprise namespace.
Profile is the AWS shared-config profile name.
Project is the GCP project ID (required for gcp_secret_manager).
Provider is the backend type (required).
Region is the AWS region (required for AWS providers).
RoleARN is the IAM role to assume (required for aws_sts).
SessionName appears in CloudTrail and the assumed-role ARN.
tls object
TLS configures TLS settings for the Vault connection.
CACert is the path to a custom CA certificate for verifying the server.
ClientCert is the path to a client certificate for mutual TLS.
ClientKey is the path to a client key for mutual TLS.
SkipVerify disables TLS verification. For dev/testing only.
VaultURL is the Azure Key Vault URL (required for azure_key_vault).
secrets object
Secrets declares named secrets to be fetched from providers. Keys are variable names (or prefixes for multi-value providers) injected into the job runtime.
property name* types.SecretSpec
Encoding specifies the file encoding: "raw" (default) or "base64".
EngineVersion is the KV engine version: 1 or 2 (default: 2).
Field extracts a single JSON key from the secret value.
From references a key in the job's SecretProviders map (required).
Mount is the Vault secret engine mount (e.g. "kv", "secret").
Name is the parameter name or ARN. Supports ":version" and ":label" suffixes.
Path is the absolute path on the node to read from.
Refresh overrides the refresh interval for this secret.
Possible values: [-9223372036854776000, 9223372036854776000, 1, 1000, 1000000, 1000000000, 60000000000, 3600000000000, 3600000000000, 10000000000]
Secret is the GCP secret name.
SecretID is the Secrets Manager secret name or ARN.
SecretName is the Azure Key Vault secret name.
SecretPath is the path within the mount.
Version pins a specific version (Vault KV v2, GCP, Azure).
VersionID selects the secret by version ID. Mutually exclusive with VersionStage.
VersionStage selects the secret version (default: AWSCURRENT).
WithDecryption controls parameter decryption (default: true).
selector object
Selector defines which nodes to run the job on
MatchExpressions selects nodes using label selector expression strings. Each expression is evaluated independently and all must match (AND logic). Supported syntax:
- Equality: "key=value" or "key==value"
- Inequality: "key!=value"
- Set inclusion: "key in (value1,value2,...)"
- Set exclusion: "key notin (value1,value2,...)"
- Existence: "key"
- Non-existence: "!key" Examples:
- "region=us-east"
- "tier in (premium,standard)"
- "environment!=prod"
- "gpu"
- "!debug"
MatchIDs selects specific nodes by their IDs. If specified, the job will only run on nodes whose ID is in this list.
match_labels object
MatchLabels selects nodes with labels that exactly match all specified key-value pairs. All labels must match (AND logic). Example: {"region": "us-east", "tier": "compute"}
timeouts object
Timeouts defines timeout configurations for the job
ExecutionTimeout is the maximum amount of time a task is allowed to run in seconds. Zero means no timeout, such as for a daemon task.
QueueTimeout is the maximum amount of time a task is allowed to wait in the orchestrator queue in seconds before being scheduled. Zero means no timeout.
TotalTimeout is the maximum amount of time a task is allowed to complete in seconds. This includes the time spent in the queue, the time spent executing and the time spent retrying. Zero means no timeout.
Type specifies what kind of workload this job runs (e.g. "pipeline", "query", "update", "config"). The scheduling behavior is derived from this type.
{
"config": {
"input": {
"file": {
"paths": [
"/var/log/app/*.log"
]
}
},
"output": {
"stdout": {}
},
"pipeline": {
"processors": [
{
"mapping": "root = this\nroot.processed_at = now()\n"
}
]
}
},
"description": "Processes application logs from edge nodes",
"labels": {
"env": "production",
"region": "us-west",
"version": "v1.2.0"
},
"name": "log-processor",
"namespace": "production",
"priority": 50,
"selector": {
"match_labels": {
"env": "production",
"role": "app-server"
}
},
"type": "pipeline"
}