Deployment Guide

End-to-end CI/CD pipeline: package your workflow, build a Docker image, push to a registry, and deploy to Kubernetes.

Overview

Each step is a single kdeps command. No Dockerfiles, no manual YAML authoring, no glue scripts.

Step 1: Validate

Run schema and dependency validation before packaging:

kdeps validate workflow.yaml

This catches YAML syntax errors, missing dependencies, circular references, and bad expressions before they reach production. Always run this in CI before packaging.

Step 2: Package

Create a portable .kdeps archive containing the workflow and all resources:

kdeps bundle package . --output dist/
# Creates: dist/my-agent-1.0.0.kdeps

The archive includes workflow.yaml, all resource files, Python requirements, data files, and assets. Respects .kdepsignore exclusions.

Step 3: Build Docker Image

Build a Docker image from the package:

kdeps bundle build dist/my-agent-1.0.0.kdeps \
  --tag registry.example.com/my-agent:v1.0.0
docker push registry.example.com/my-agent:v1.0.0

No Dockerfile needed -- kdeps generates a multi-stage build from your workflow config. GPU support is a flag away:

kdeps bundle build dist/my-agent-1.0.0.kdeps \
  --tag registry.example.com/my-agent:v1.0.0-gpu \
  --gpu cuda
docker push registry.example.com/my-agent:v1.0.0-gpu

See Docker Deployment for base OS selection, offline mode, and custom image configuration.

Step 4: Deploy to Kubernetes

Generate Kubernetes manifests and apply them:

kdeps export k8s dist/my-agent-1.0.0.kdeps \
  --image registry.example.com/my-agent:v1.0.0 \
  --output k8s.yaml

kubectl apply -f k8s.yaml
kubectl rollout status deployment/my-agent

The generated manifests include Deployment, Service, and environment configuration -- all driven from workflow.yaml. Override replicas, resource limits, and env vars with flags.

See Kubernetes Deployment for full manifest structure, health checks, and multi-replica configuration.

CI/CD Pipeline Example

GitHub Actions

# .github/workflows/deploy.yml
name: Deploy
on:
  push:
    tags: ['v*']

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install kdeps
        run: curl -fsSL https://kdeps.io/install.sh | bash

      - name: Validate
        run: kdeps validate workflow.yaml

      - name: Package
        run: kdeps bundle package . --output dist/

      - name: Build and Push
        run: |
          kdeps bundle build dist/*.kdeps \
            --tag ${{ secrets.REGISTRY }}/my-agent:${{ github.ref_name }}
          docker push ${{ secrets.REGISTRY }}/my-agent:${{ github.ref_name }}
        env:
          DOCKER_CONFIG: ${{ secrets.DOCKER_CONFIG }}

      - name: Deploy to K8s
        run: |
          kdeps export k8s dist/*.kdeps \
            --image ${{ secrets.REGISTRY }}/my-agent:${{ github.ref_name }} \
            --output k8s.yaml
          kubectl apply -f k8s.yaml

GitLab CI

# docker-compose.yml
deploy:
  stage: deploy
  only:
    - tags
  script:
    - curl -fsSL https://kdeps.io/install.sh | bash
    - kdeps validate workflow.yaml
    - kdeps bundle package . --output dist/
    - kdeps bundle build dist/*.kdeps --tag $CI_REGISTRY_IMAGE:$CI_COMMIT_TAG
    - docker push $CI_REGISTRY_IMAGE:$CI_COMMIT_TAG
    - kdeps export k8s dist/*.kdeps --image $CI_REGISTRY_IMAGE:$CI_COMMIT_TAG --output k8s.yaml
    - kubectl apply -f k8s.yaml

Standalone Binaries (No Docker)

For edge deployments that can't run containers, use the prepackage flow:

kdeps bundle package . --output dist/

The .kdeps archive can be deployed directly on any machine with kdeps installed:

export KDEPS_API_AUTH_TOKEN=api-secret
kdeps run dist/my-agent-1.0.0.kdeps --port 16395

See Standalone Binaries for self-contained single-binary exports.

See Also

• Docker Deployment -- image build details, base OS, GPU support
• Kubernetes Deployment -- manifest structure, health checks
• Standalone Binaries -- single-binary edge exports
• CLI: Packaging Commands -- all bundle and export commands

Optional: LLM server appliance (not an agent)

To deploy a shared OpenAI-compatible inference server (no workflow) for many kdeps clients:

kdeps llm list
kdeps llm build --engine ollama --model llama3.2 --tag registry.example.com/llm:v1
docker push registry.example.com/llm:v1
kdeps llm export k8s --engine ollama --image registry.example.com/llm:v1 -o llm.yaml
kubectl apply -f llm.yaml
kdeps llm client-config --url http://kdeps-llm-ollama:8000/v1

Stock engines include ollama, llamafile, gguf / llama-server, llamacpp, vllm, tgi, sglang, and localai. GPU engines require --gpu cuda (or another profile).

See LLM Server Appliance and LLM Commands.

HTTPS on a custom domain

After deploy, enable HTTPS either at the load balancer/Ingress or in-process:

settings:
  letsEncrypt:
    domain: api.example.com
    email: ops@example.com
  apiServer:
    hostIP: "0.0.0.0"
    portNum: 443

Open ports 80 and 443, point DNS at the service, and persist cacheDir (default ~/.kdeps/letsencrypt). Details: TLS and HTTPS.