ork serve

6 min read

Inspect and validate Internal Developer Platform (Serve) configurations.

The Serve is the contract between platform teams and developers. These commands let you inspect and validate Serve configurations without needing to run the gateway or access a cluster.

Commands

CommandDescription
validateValidate Serve configuration in a Katalog
schemaShow the flat schema for an Serve target
fieldsList all Serve fields with their paths and types
tokensShow token permissions for a CRD
targetsList all Serve targets in a Katalog
can-iCheck if a token can perform an operation
responseShow the Serve response configuration

ork serve validate

Validate Serve configuration in a Katalog.

This runs the same serve-specific validations as ork validate, but only for Serve concerns: fields, paths, tokens, response config, and namespace rules. It does not check the full Katalog schema — only the Serve portions.

ork serve validate

Flags

FlagShortDescription
--fullShow a detailed breakdown of the Serve configuration for each serve-enabled CRD.

Examples

# Validate Serve configuration
ork serve validate

Output

✓ Serve configuration is valid

With --full

# Validate Serve configuration with detailed breakdown
ork serve validate --full

Output

Serve Configuration Summary
──────────────────────────────────────────────────────────────────────

✅ application
  target: smartapp  /  kind: AppRequest
  name:      "{{ repoSlug .spec.repository }}"
  namespace: "{{ teamName }}-{{ environmentName }}"
  fields:    12 total (spec: 8, labels: 2, annotations: 2)
  nested:    5 path(s)
  tokens:    4 token(s) with restrictions
  response:  default: true, payload: 4, exclude: 3
  poll:      url, field

✅ database
  target: db  /  kind: Database
  name:      "{{ repoSlug .spec.repository }}"
  namespace: "{{ teamName }}"
  fields:    6 total (spec: 4, labels: 1, annotations: 1)
  tokens:    none (all tokens allowed)
  response:  none (default CR response)

──────────────────────────────────────────────────────────────────────
✓ Serve configuration is valid
  2 serve-enabled CRD(s)

ork serve schema

Show the flat schema for an Serve target.

This displays the fields that callers can submit for a target, including their labels, types, enums, and paths. The output is the same flat field structure returned by the gateway’s GET /api/v1/schema?target=<t> endpoint.

ork serve schema [flags]

Flags

FlagShortDescription
--target-tTarget to show schema for
--kind-kKind to show schema for
--name-nCRD name to show schema for

One of --target, --kind, or --name is required.

Examples

# Show schema by target
ork serve schema --target smartapp

# Show schema by kind
ork serve schema --kind AppRequest

# Show schema by CRD name
ork serve schema --name application

Output

Schema for: application (target: smartapp)
──────────────────────────────────────────────────────────────────────
FIELD           LABEL            TYPE    PATH                    REQUIRED
repository      Repository       string  app.repository          ✓
image           Container Image  string  app.image               ✓
cpu             CPU Request      string  app.resources.cpu
replicas        Replicas         integer scaling.replicas

ork serve fields

List Serve fields with their paths and types.

This shows fields declared in serve.fields and serve labels/annotations across all serve-enabled CRDs. With --target, --kind, or --name, shows fields for a specific CRD.

ork serve fields

Flags

FlagShortDescription
--target-tTarget to show fields for
--kind-kKind to show fields for
--name-nCRD name to show fields for
--sort-bySort fields by "name" (default) or "order"

Examples

# List all fields across all CRDs
ork serve fields

# List fields for a specific target
ork serve fields --target smartapp

# List fields for a specific kind
ork serve fields --kind AppRequest

# List fields for a specific CRD name
ork serve fields --name application

# Sort fields by order (as declared in the Katalog)
ork serve fields --target smartapp --sort-by order

Output (All fields)

Serve Fields
──────────────────────────────────────────────────────────────────────

CRD: application (target: smartapp)
  FIELD           TYPE    PATH                    SOURCE
  cpu             string  app.resources.cpu       spec
  environment     string                          label
  image           string  app.image               spec
  repository      string  app.repository          spec
  team            string                          label

Total: 5 fields across 1 CRD

Output (Specific CRD)

Fields for: application (target: smartapp)
──────────────────────────────────────────────────────────────────────
FIELD           TYPE    PATH                    SOURCE      REQUIRED
cpu             string  app.resources.cpu       spec
environment     string                          label
image           string  app.image               spec        ✓
repository      string  app.repository          spec        ✓
team            string                          label       ✓

Output (Sorted by order)

Fields for: application (target: smartapp)
──────────────────────────────────────────────────────────────────────
FIELD           TYPE    PATH                    SOURCE      REQUIRED  ORDER
repository      string  app.repository          spec        ✓         1
image           string  app.image               spec        ✓         2
team            string                          label       ✓         3
cpu             string  app.resources.cpu       spec                  4
environment     string                          label                 5

ork serve tokens

Show token permissions for an serve-enabled CRD.

This displays the serve.tokens configuration, including which tokens have access, their permissions (../global/schema/resources), and namespace restrictions.

ork serve tokens [flags]

Flags

FlagShortDescription
--target-tTarget to show tokens for
--kind-kKind to show tokens for
--name-nCRD name to show tokens for

One of --target, --kind, or --name is required.

Examples

# Show tokens by target
ork serve tokens --target smartapp

Output

Token permissions for CRD: application (target: smartapp)
──────────────────────────────────────────────────────────────────────
TOKEN            GLOBAL  SCHEMA  RESOURCES           NAMESPACES
control-center   *       *       *                   *
ci-pipeline              get,list create,update,get,list staging
monitoring               get,list get,list           *

ork serve targets

List all serve-enabled targets in a Katalog.

This shows each target, its CRD kind, and whether it has fields defined.

ork serve targets

Examples

# List all targets
ork serve targets

Output

Serve Targets
──────────────────────────────────────────────────────────────────────
TARGET      KIND        FIELDS  TOKENS
smartapp    AppRequest  12      yes
database    Database    8       no

2 target(s)

ork serve can-i

Check if a token can perform an operation.

This evaluates the same permission checks that the gateway applies to incoming Gateway API requests. It considers token existence, permissions (global/schema/resources scopes), namespace restrictions, and target existence.

ork serve can-i [flags]

Flags

FlagShortDescription
--token-TToken name to check (required)
--target-tTarget to check
--kind-kKind to check
--name-nCRD name to check
--operation-oOperation to check (required)
--namespace-NNamespace to check (default: all namespaces)
--class-cEndpoint class to check (resources, schema)

One of --target, --kind, or --name is required.

Examples

# Check if token can create
ork serve can-i --token control-center --target smartapp --operation create

# Check if token can delete in a namespace
ork serve can-i --token ci-pipeline --target smartapp --operation delete --namespace staging

# Check if token can list
ork serve can-i --token monitoring --target smartapp --operation list

Output (Allowed)

✓ control-center can create on "smartapp"

Output (Denied)

✗ ci-pipeline cannot delete on "smartapp" in namespace "staging"
  Reason: token "ci-pipeline" does not have "delete" permission for resources class
  Available: 
    - schema:    get
    - resources: create,update,list,get

ork serve response

Show the Serve response configuration.

This displays what callers will see in the Gateway API response based on serve.config.response. It shows default: true/false, payload fields (with their template expressions), excluded paths, and poll URL configuration.

No cluster access is required — this reads the Katalog directly.

ork serve response [flags]

Flags

FlagShortDescription
--target-tTarget to show response for
--kind-kKind to show response for
--name-nCRD name to show response for
--preview-pShow a sample response preview

One of --target, --kind, or --name is required.

Examples

# Show response config
ork serve response --target smartapp

# Show response config with preview
ork serve response --target smartapp --preview

Output

Response configuration for: application (target: smartapp)
──────────────────────────────────────────────────────────────────────

default: true

Payload fields:
  FIELD         EXPRESSION
  phase         '{{ .status.phase }}'
  serviceURL    '{{ serviceURL }}'
  queueDepth    '{{ .external.queueDepth.value | default 0 }}'
  nextSteps     '{{ nextSteps }}'

Excluded paths:
  ✗ metadata.managedFields
  ✗ status.observedGeneration
  ✗ metadata.name

Poll URL:
  url:   "{{ devServerURL }}"
  field: "status.phase"

With --preview

──────────────────────────────────────────────────────────────────────

Response preview (templates shown as-is, not resolved):

{
  "phase": "{{ .status.phase }}",
  "serviceURL": "{{ serviceURL }}",
  "queueDepth": "{{ .external.queueDepth.value | default 0 }}",
  "nextSteps": "{{ nextSteps }}"
}

Excluded fields:
  ✗ metadata.managedFields
  ✗ status.observedGeneration
  ✗ metadata.name