diff --git a/README.md b/README.md index 2c1ded2..91ce922 100644 --- a/README.md +++ b/README.md @@ -55,12 +55,99 @@ tycho is a python package, and is developed using normal python package patterns ## Tycho Labels -#### Label: executor +### Label: executor -For each application (pod) that is created is labeled with `executor: tycho` which allows for a concise way to list all of the pods that it creates +For each application (pod) that is created is labeled with `executor: tycho` which allows +for a concise way to list all of the pods that it creates - kubectl get pods -l executor=tycho +### Label: app-name +The name of the app (e.g. JupyterLab). A label to specify what application the +pod/deployment is executing on behalf of. + +### Label: name + +As above, but extended with a unique-ifying guid + +### Label: username + +The name of the user who is logged in via helx-appstore for which a +tycho-created pod is executing. + +### A useful kubectl + +Here is a useful way to list all pods for all users listing the pod, application +name and user for which it's executing + + kubectl get pod -l executor=tycho -L app-name -L username --sort-by username + +## Source Code + +### Tycho System Management (actions.py) + +This module provides a set of functionalities to manage distributed systems of cloud-native containers. It allows for creating, monitoring, and deleting systems running on abstracted compute fabrics. + +#### Overview + +- **TychoResource**: The base class for handling Tycho requests, providing common functionality such as request validation against a predefined schema. +- **StartSystemResource**: Handles system initiation, parsing, modeling, emitting orchestrator artifacts, and executing a system. +- **DeleteSystemResource**: Manages system termination, using a system's GUID to eliminate all its running components. +- **StatusSystemResource**: Provides the status of executing systems, allowing status checks either globally or for specific systems. +- **ModifySystemResource**: Offers functionality to modify a system's specifications like name, labels, and resources (CPU and memory). + +#### Key Functions + +- `validate(request, component)`: Validates a request against the API schema. +- `create_response(result, status, message, exception)`: Creates a formatted response, handling exceptions and status modifications. +- `post(request)`: For each resource class, processes the POST request to perform the respective actions (start, delete, status check, or modify a system). + +### Tycho Client and Services Management (client.py) + +This module offers a comprehensive suite of functionalities to manage, monitor, and interact with distributed systems and services, particularly focusing on cloud-native container orchestration using Kubernetes. + +#### Key Components + +- **TychoService**: Represents a service endpoint, holding details like name, IP address, port, and resource utilization. +- **TychoStatus**: Models the response from a status request, encapsulating the status, services, and messages. +- **TychoSystem**: Represents a running system, handling system status, name, identifier, services, and connection strings. +- **TychoClient**: The core Python client for interacting with the Tycho API, enabling actions like start, status, delete, and modify. +- **TychoClientFactory**: Facilitates locating and connecting to the Tycho API within a Kubernetes cluster. +- **TychoApps**: Manages applications, supporting actions like cloning repositories, extracting metadata, and system specifications. + +#### Features + +- Service utilization tracking, converting and aggregating resource metrics. +- Comprehensive system representation, including status, service details, and operations. +- Dynamic interaction with Tycho API to start, stop, modify, and retrieve the status of services. +- Environment-sensitive Kubernetes configuration loading for in-cluster or external usage. +- CLI interface for direct interaction, supporting operations like up, down, status, and modify on systems. + +### Core (core.py) + +The `Tycho` library serves as a sophisticated abstraction layer atop cloud-native container orchestration platforms, enhancing system architecture and policy enforcement. It aims to simplify the design, decision-making, automation, testing, and enforcement processes for teams working with Kubernetes. + +## Features +- **Initialization**: Constructs a Tycho component with configurable backplane and system settings. +- **Compute Fabric API**: Provides access to the compute fabric's code emitter based on constructor specifications. +- **System Parsing**: Transforms JSON requests into abstract syntax trees, enabling structured system specifications that include environment variables, services, and networking rules. +- **Modification Parsing**: Allows for the modification of system metadata and specifications based on GUID, labels, and resource allocations. +- **Backplane Validation**: Checks for valid compute backplanes and lists supported backplanes, facilitating integration with various compute fabrics. + +Designed to work seamlessly with Kubernetes, Tycho leverages a configuration-first approach, promoting clarity and efficiency in deploying and managing containerized applications. + +### TychoContext (context.py) + +The `TychoContext` library provides a comprehensive Python interface for loading, understanding, and utilizing application registries within a platform environment. It leverages a declarative metadata repository (YAML-based) to outline available applications, including their basic metadata, repositories for further details, and integration with the Tycho system for app management. + +Key Features: +- **Principal Class**: Abstracts system identity with support for access and refresh tokens. +- **App Registry Loading**: Dynamically loads app registry and default configurations from YAML files, supporting modifications via environment variables. +- **Configuration Management**: Includes utilities for merging app configurations and handling inheritance and mixins from different contexts. +- **App Management**: Facilitates starting, stopping, updating, and querying application statuses using the Tycho system, with detailed logging and error handling. +- **Environment and Security**: Manages application environment variables, security contexts, and integrates with Kubernetes for service accounts and resource management. +- **Proxy and Integration Support**: Provides mechanisms for proxy rewrite rules and external integrations like Gitea. + +Designed for flexibility and ease of integration, this library supports development and testing phases with a NullContext for mock interactions, alongside the primary TychoContext for live environments. ### "proxy_rewrite" Feature Overview: