Workload

A Workload defines the runtime specification for a Component in OpenChoreo. It describes what container image to run, what network endpoints to expose, what configuration to inject, and what dependencies the component has on other components and on managed infrastructure. The platform uses this specification to generate the appropriate Kubernetes resources, including Deployments, Services, HTTPRoutes, and NetworkPolicies.

Each component has exactly one Workload, linked to it through the owner field.

This page is the reference for the Workload resource itself. For the workload.yaml file you put in a source repository, see Workload Descriptor.

How a Workload Is Created

Starting point	What you author	What reaches the control plane
A pre-built image in a registry	A Workload CR alongside the Component	Your CR, as written
Source code built by an OpenChoreo CI workflow	A workload descriptor added to your repository	A Workload CR generated by the build

In both cases the end result is one Workload CR owned by one Component.

Structure

A Workload spec has the following top-level fields:

apiVersion: openchoreo.dev/v1alpha1
kind: Workload
metadata:
  name: my-service-workload
  namespace: default
spec:
  owner:
    projectName: my-project
    componentName: my-service
  container:
    # Container specification
  endpoints:
    # Network endpoints
  dependencies:
    # Dependencies on other components and on Resources

Owner

The owner field links the Workload to its Component and Project. This field is immutable after creation.

Field	Type	Required	Description
projectName	string	Yes	Name of the project that owns this workload
componentName	string	Yes	Name of the component that owns this workload

Container

The container field defines what to run. Only the image field is required.

Field	Type	Required	Description
image	string	Yes	OCI image to run (digest or tag)
command	[]string	No	Container entrypoint
args	[]string	No	Arguments for the entrypoint
env	[]EnvVar	No	Environment variables
files	[]File	No	File configurations and secrets

Environment Variables

Environment variables can be set as literal values or referenced from secrets:

container:
  image: myregistry/my-service:v1.0.0
  env:
    - key: LOG_LEVEL
      value: info
    - key: DB_PASSWORD
      valueFrom:
        secretKeyRef:
          name: db-secrets
          key: password

Each env entry must have exactly one of value or valueFrom set.

Files

Files can be mounted into the container from literal content or secrets:

container:
  image: myregistry/my-service:v1.0.0
  files:
    - key: config.yaml
      mountPath: /etc/config
      value: |
        server:
          port: 8080
    - key: tls.crt
      mountPath: /etc/tls
      valueFrom:
        secretKeyRef:
          name: tls-certs
          key: certificate

Each file entry requires key and mountPath, and must have exactly one of value or valueFrom set.

Endpoints

Endpoints define the network interfaces that the component exposes. They are specified as a map where each key is the endpoint name:

endpoints:
  http:
    type: HTTP
    port: 8080
    visibility:
      - external
    basePath: /api/v1
  grpc:
    type: gRPC
    port: 9090
    visibility:
      - namespace

Endpoint Fields

Field	Type	Required	Description
type	string	Yes	Protocol type: HTTP, gRPC, GraphQL, Websocket, TCP, UDP
port	int32	Yes	Port number exposed by the endpoint (1-65535)
targetPort	int32	No	Container port to forward to (defaults to port)
visibility	[]string	No	Additional visibility scopes beyond the implicit project visibility
basePath	string	No	Base path of the API exposed via the endpoint
displayName	string	No	Human-readable name for the endpoint
schema	object	No	API schema definition (e.g., OpenAPI spec)

Endpoint Visibility

Every endpoint automatically gets project visibility, meaning it is accessible to other components within the same project and environment. The visibility array adds additional scopes:

Visibility	Description
project	Accessible within the same project and environment (implicit for all endpoints)
namespace	Accessible across all projects in the same namespace and environment
internal	Accessible across all namespaces in the deployment
external	Accessible from outside the deployment, including public internet

Visibility levels control both routing (HTTPRoutes) and network access (NetworkPolicies). For example, an endpoint with external visibility gets an HTTPRoute on the external gateway and a NetworkPolicy allowing ingress from non-OpenChoreo namespaces, while namespace visibility allows cross-project traffic within the same namespace.

Dependencies

The dependencies field declares what your component needs from the rest of the platform. OpenChoreo resolves each dependency per environment and injects the result into your container: the endpoint details for an endpoint dependency, the Resource's outputs for a resource dependency. Endpoint dependencies additionally configure the NetworkPolicies that allow the call. For both kinds, the deployment is held until every dependency is ready.

dependencies:
  endpoints:
    - component: backend-api
      name: http
      visibility: project
      envBindings:
        address: BACKEND_API_URL
  resources:
    - ref: my-postgres
      envBindings:
        host: DB_HOST
        port: DB_PORT
        username: DB_USER
        password: DB_PASSWORD
        database: DB_NAME

Field	Type	Description
endpoints	array	Endpoints exposed by other components, consumed at project or namespace visibility
resources	array	Outputs of a project-bound Resource, such as a database, queue, cache, or object store

A Workload can declare up to 50 of each. The full field reference for both lives on their own pages:

• Endpoint Dependencies — consuming another component's endpoint
• Resource Dependencies — consuming a Resource's outputs through envBindings and fileBindings

Environment-Specific Values

The Workload is the base specification, shared by every environment. To change a value in one environment only use workloadOverrides on the ReleaseBinding for that environment. See Environment Overrides.

Example

Here is a complete Workload example for a REST service with an external endpoint:

apiVersion: openchoreo.dev/v1alpha1
kind: Workload
metadata:
  name: greeter-service-workload
  namespace: default
spec:
  owner:
    projectName: default
    componentName: greeter-service
  container:
    image: cr.openchoreo.dev/openchoreo/samples/greeter-service:latest
    args:
      - --port
      - "9090"
  endpoints:
    http:
      type: HTTP
      port: 9090
      visibility:
        - external

Related Resources

• Workload Descriptor - The workload.yaml file that CI builds turn into a Workload CR
• Workload API Reference - Full CRD specification
• Component - Components that own workloads
• Endpoint Dependencies - Consuming endpoints from other components
• Resource Dependencies - Consuming managed infrastructure
• Environment Overrides - Changing workload values per environment