Metadata-Version: 2.4
Name: ostrich-sdk
Version: 0.2.4
Summary: Ostrich SDK Core CLI and Templating Engine
Author: Ostrich Team
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: cachetools>=6.0.0
Requires-Dist: certifi>=2024.0.0
Requires-Dist: charset-normalizer>=3.0.0
Requires-Dist: go-template>=0.0.3
Requires-Dist: google-auth>=2.0.0
Requires-Dist: idna>=3.0
Requires-Dist: kubernetes>=28.0.0
Requires-Dist: oauthlib>=3.2.0
Requires-Dist: pyasn1>=0.5.0
Requires-Dist: pyasn1-modules>=0.3.0
Requires-Dist: python-dateutil>=2.8.0
Requires-Dist: PyYAML>=6.0
Requires-Dist: requests>=2.31.0
Requires-Dist: requests-oauthlib>=1.3.0
Requires-Dist: rsa>=4.9
Requires-Dist: six>=1.16.0
Requires-Dist: urllib3>=2.0.0
Requires-Dist: websocket-client>=1.6.0
Requires-Dist: tqdm>=4.66.0
Requires-Dist: jinja2>=3.1.0
Requires-Dist: MarkupSafe>=2.1.0
Requires-Dist: jsonpath-ng>=1.6.0
Requires-Dist: pytest>=7.0.0
Requires-Dist: colorama>=0.4.6
Requires-Dist: pytest-cov>=4.0.0
Requires-Dist: semver>=3.0.0
Requires-Dist: glom>=23.0.0
Requires-Dist: jsonschema>=4.20.0
Requires-Dist: envsubst
Dynamic: license-file

# Ostrich SDK

Deploy like an Ostrich! 🦩

**Ostrich SDK** is a powerful, template-driven application deployment engine and orchestration platform. It provides a unified interface for DevOps workflows, including template management, local containerized execution, remote SSH/Kubernetes orchestration, registry management, and plugin execution.

By leveraging parameterized template packages called **osplates**, developers can easily package, configure, and deploy application architectures across diverse environments without managing low-level orchestration configurations directly.

---

## 🚀 Key Features

- **Template-driven (Osplates):** Build once, deploy anywhere using customizable parameters and templates.
- **Jinja2 Templating Engine:** Parameterize configurations safely using custom Jinja2 delimiters (`[[` and `]]`) to avoid conflicts with Helm or Kubernetes syntax.
- **Docker/Podman Sandbox:** Execute deployment tasks locally within isolated containers without cluttering host machines with toolchains (Helm, Kubernetes CLI, `jq`, `yq`, etc.).
- **Remote K8s/SSH Orchestration:** Deploy and manage workloads on remote Kubernetes endpoints over secure SSH tunnel connections using `ostr`.
- **Registry & OCI Management:** Built-in commands to authenticate, list, pull, and push OCI registry images and packages.
- **Plugin Architecture:** Define modular application lifecycles with declarative task definitions in `ostrich.yaml`.

---

## 🏗️ System Architecture Overview

The Ostrich SDK is composed of three primary components:

1. **`ost-core` (The Engine):** A Python 3 execution engine (`ost`) that processes templates, resolves configuration parameters, and executes deployment tasks using flexible runners (`inprocess`, `shell`, `container`).
2. **`ostd` (Local Container CLI):** A compiled Go utility that launches the `ost` engine inside a local Docker/Podman container, mounting workspace files and host credential configs (e.g., `.kube/config`, `.docker/config.json`) seamlessly.
3. **`ostr` (Remote K8s CLI):** A compiled Go utility that connects to an SSH-enabled agent pod running inside a remote Kubernetes cluster to sync files and execute `ost` deployment tasks remotely.

---

## 🚀 Quickstart

### 1. Build and Install CLIs
To build the CLI binaries (`ostd` and `ostr`), run the build script:
```bash
./scripts/build.sh
```
The compiled binaries for Linux, macOS, and Windows will be placed in the `bin/` directory. Copy the appropriate binaries to your system `PATH` (e.g. `/usr/local/bin/`).

### 2. Installing Python Engine via `pip`
To install the `ost` Python CLI and engine directly from PyPI:

```bash
pip install ostrich-sdk
```

Or install from local repository source:
```bash
# Install locally in editable mode
pip install -e .

# Or install standard package from local source
pip install .
```
Verify the installation:
```bash
ost --version
ost help
```

> 📘 **Developer Guide**: For instructions on setting up PyPI publishing credentials and automated GitHub Action releases, see [PYPI.md](PYPI.md).


### 3. Running Tasks Locally with `ostd`
Using `ostd` allows you to execute deployment tasks locally without setting up the core Python environment on your host machine.

```bash
# Check version
ostd --version

# Show current default Docker image
ostd image show

# Set custom default Docker image & tag
ostd image ghcr.io/rockops/ostrich-sdk:0.2.1

# Remove custom image setting (revert to default)
ostd image --rm

# List available templates
ostd template list

# Inspect template details
ostd template describe <template-name>

# Generate a sample configuration file
ostd template config <template-name>

# Dry run deployment task
ostd -dr run deploy

# Execute deployment task
ostd run deploy
```

### 3. Running Tasks Remotely with `ostr`
`ostr` lets you orchestrate deployments on a remote Kubernetes cluster containing an Ostrich SDK agent.

```bash
# Initialize connection to remote endpoint
ostr init <endpoint_name> <ip_address>

# Manage and select active endpoints
ostr endpoint list
ostr endpoint select <endpoint-name>

# Synchronize local files and execute task remotely
ostr run deploy

# Open interactive remote shell
ostr ssh
```

---

## 🛠️ Plugin & Osplate Development

### Plugin Structure (`ostrich.yaml`)
Applications managed by Ostrich SDK define their lifecycle using an `ostrich.yaml` descriptor in the root directory:

- **Metadata:** Name, version, description, and dependencies.
- **Template / Osplate Kind:** Specifies the osplate blueprint to extend.
- **Tasks:** Pre-defined operations (e.g., `deploy`, `package`, `test`) consisting of execution steps.
- **Configuration:** Custom template variables and default parameter overrides.

### Example `ostrich.yaml`

```yaml
name: my-plugin
version: 1.0.0
description: Custom application plugin

tasks:
  deploy:
    description: Deploy application to Kubernetes
    steps:
      - name: Build Docker image
        run: docker build -t my-image .
      - name: Push to registry
        run: docker push my-image
      - name: Deploy to Kubernetes
        run: kubectl apply -f k8s/
```

---

## 📦 Registry & Operations Reference

### Standard Commands

| Command | Description |
|---------|-------------|
| `init` | Setup connection to a remote endpoint |
| `endpoint` | Manage endpoints (list, select, set) |
| `ssh` | Open interactive shell on remote endpoint |
| `put` | Upload files to remote endpoint |
| `docker` | Run docker commands remotely |
| `kubectl` | Run kubectl commands remotely |
| `run` | Execute a task defined in a plugin/osplate |
| `cert install` | Install a trusted certificate remotely |
| `host` | Add a host entry remotely |
| `version` | Display version information |

### Template Operations

| Command | Description |
|---------|-------------|
| `template list` | List available plugin templates (osplates) |
| `template describe <name>` | Get detailed information about a template |
| `template config <name>` | Generate sample configuration file |

### Registry Operations

| Command | Description |
|---------|-------------|
| `registry login <url>` | Authenticate with an OCI registry |
| `registry ls <url>` | List images in a registry |
| `registry pull <image>` | Pull an image from registry |
| `registry push <image>` | Push an image to registry |

---

## ⚙️ Configuration & Environment

### Global Configuration

```bash
# Display current configuration
ost config get

# Set configuration key-value
ost config set <key> <value>
```

### Environment Variables

| Variable | Description |
|----------|-------------|
| `PRIVATE_DOCKER_REGISTRY` | Default private Docker registry URL |
| `PRIVATE_HELM_REGISTRY` | Default private Helm registry URL |
| `KUBECONFIG` | Path to host Kubernetes configuration file |

---

## 📚 Documentation & Reference

For additional technical specifications, architectural details, and guides:

- [System Description & Architecture (DESCRIPTION.md)](file:///home/ben/src/ostrich/ostrich-sdk/DESCRIPTION.md) - Deep dive into core engine logic, volume mappings, and remote sync.
- [Plugin Creation Guide (PLUGIN.md)](file:///home/ben/src/ostrich/ostrich-sdk/PLUGIN.md) - Complete guide on how to create, document, test, and publish custom Osplates.
- [AI & Developer Guide (CLAUDE.md)](file:///home/ben/src/ostrich/ostrich-sdk/CLAUDE.md) - Build scripts, test runner commands, and development workflows.
- [License (LICENSE)](file:///home/ben/src/ostrich/ostrich-sdk/LICENSE) - Project license information.

---

## 🤝 Contributing & Support

Contributions are welcome! Please refer to [CLAUDE.md](file:///home/ben/src/ostrich/ostrich-sdk/CLAUDE.md) for development rules and guidelines.

For issues and support, please open an issue on the GitHub repository.
