<hr/> <a href="https://github.com/stjude-rust-labs/planetary/actions/workflows/CI.yml" target="_blank"> <img alt="CI: Status" src="https://github.com/stjude-rust-labs/planetary/actions/workflows/CI.yml/badge.svg" /> </a> <a href="https://crates.io/crates/planetary" target="_blank"> <img alt="crates.io version" src="https://img.shields.io/crates/v/planetary"> </a> <img alt="crates.io downloads" src="https://img.shields.io/crates/d/planetary"> <a href="https://github.com/stjude-rust-labs/planetary/blob/main/LICENSE-APACHE" target="_blank"> <img alt="License: Apache 2.0" src="https://img.shields.io/badge/license-Apache 2.0-blue.svg" /> </a> <a href="https://github.com/stjude-rust-labs/planetary/blob/main/LICENSE-MIT" target="_blank"> <img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-blue.svg" /> </a> A Kubernetes-based task executor for the Task Execution Service (TES) specification. <a href="https://github.com/stjude-rust-labs/planetary/issues/new?assignees=&title=Descriptive%20Title&labels=enhancement">Request Feature</a> · <a href="https://github.com/stjude-rust-labs/planetary/issues/new?assignees=&title=Descriptive%20Title&labels=bug">Report Bug</a> · ⭐ Consider starring the repo! ⭐

📚 About Planetary

Planetary is an implementation of the GA4GH Task Execution Service (TES) API that executes tasks in a Kubernetes cluster.

⚠️ Security Notice

Though we've made a best-effort attempt to incorporate security best practices into Planetary and its associated Helm chart where possible, Planetary itself does not claim to be an end-to-end, fully secure application and deployment.

Ensuring a high level of security is inherently contextual, and requirements vary significantly depending on your environment and operational policies. As such, several additional steps are needed to effectively deploy and secure your Kubernetes environment, the Planetary Helm chart, and the Planetary application.

It is your responsibility to implement, verify, and continuously monitor all aspects of security to ensure they meet your standards and adequately protect your environment.

As a starting point, we recommend you review the following aspects of your deployment and the Helm chart. Keep in mind that this list is non-exhaustive, so you should do your own research to create a complete list of concerns to consider in your situation.

Ingress and external exposure. The services provided by Planetary include no authentication or authorization at all and will accept and execute unauthenticated requests if you do not take action to secure them further. It is imperitive that you restrict these services using external authentication and authorization mechanisms. Further, we encourage you to review any Services or Ingress resources included in the chart to confirm they are exposed only as needed. Ensure TLS termination, authentication, authorization, and rate-limiting are configured according to your policies, and integrate the service with a web application firewall.
RBAC permissions. We've scoped roles and bindings according to what we believe to be least-privilege access. Review these to ensure they align with your internal access control policies and compliance standards.
Pod security contexts. We’ve configured workloads to run as non-root and use read-only file systems where possible. These measures help limit container privileges and reduce the attack surface. Confirm these settings meet your container hardening requirements for all deployments and containers.
Network policies. We include policies to restrict pod-to-pod ingress and egress traffic, balancing security with ease of configuration. Validate that these meet your segmentation, isolation, and ingress/egress control goals.
Secrets management. We've defined Kubernetes Secrets where needed and structured their use for secure injection. Verify these secrets meet your standards for confidentiality, access control, and rotation.
Credentials. This chart does not provide default passwords or API keys. You must set secure, unique credentials for all components before deployment.
Resource limits and requests. We've set default CPU and memory constraints to encourage efficient scheduling and prevent resource exhaustion. Adjust these for your expected workloads.
Container images and supply chain security. We use version-pinned images from known registries. Review these to ensure they come from sources you trust, are vulnerability-scanned, and, where appropriate, have verified signatures.
Monitoring, logging, and alerting. Implement robust observability for timely incident detection and response. Configure logging to avoid exposing sensitive information, and ensure log retention complies with your policies.
Automated compliance scanning. Use automated Kubernetes security scanners to verify compliance with your organizational policies.
Upgrades and patch management. Keep Planetary and its dependencies up-to-date. We may publish chart updates in response to vulnerabilities, but you are responsible for monitoring for published updates and applying them promptly.
Cluster environment assumptions. This chart assumes it is deployed into a hardened Kubernetes cluster (e.g., restricted API server access, encrypted etcd, secure CSI drivers). Ensure your cluster meets these prerequisites.
Backups and disaster recovery. If Planetary stores persistent state in your environment, implement a tested backup and restore process.

We recommend regularly auditing your deployment to ensure continued security and operational integrity. Default settings may not be sufficient for all use cases—review and customize configurations as appropriate for your environment.

Architecture

Planetary is made up of five components:

TES API Service - this component is responsible for handling requests from TES API clients; it interacts with the Orchestrator Service and the Planetary Database.
Orchestrator Service - this component is responsible for creating and managing the Kubernetes resources used to execute tasks; it interacts with the Kubernetes API Server and the Planetary Database.
Task Monitoring Service - this component is responsible for watching for orphaned pods and requesting an orchestrator to adopt the pod; it interacts with the Orchestrator Service and the Planetary Database.
Planetary Database - this component stores the state of the TES tasks and the Kubernetes pods used to execute tasks; PostgreSQL is currently the only supported database.
Transporter - this component is a responsible for downloading task inputs from cloud storage to the Kubernetes storage before a task starts and also for uploading task outputs from Kubernetes storage to cloud storage after a task has completed.

There are currently four images created for use with Planetary:

stjude-rust-labs/planetary-api - implements the TES API Service.
stjude-rust-labs/planetary-orchestrator - implements the Orchestrator Service.
stjude-rust-labs/planetary-monitor - implements the Task Monitor Service.
stjude-rust-labs/planetary-transporter - implements the Transporter used for downloading task inputs and uploading task outputs.

Supported Cloud Storage

Planetary supports the following cloud storage services:

Azure Blob Storage : authentication is performed via signed requests using a Azure Storage shared access key.
AWS S3: authentication is performed via signed requests using an AWS Access Key Id and AWS Secret Access Key.
Google Cloud Storage: authentication is performed via signed requests using an HMAC Access Key and HMAC Secret.

See the transporter.storage Helm chart values for configuring a Planetary deployment.

Task Execution

Planetary runs each TES task by scheduling a single Kubernetes pod for the task.

The task pod consists of several containers:

An init container for downloading inputs.
An init container for each TES task executor.
A main container for uploading outputs.

Because TES task executors are expected to be run sequentially on the same node, the executors cannot be sidecar or main containers of the pod as they run in parallel.

As a result of running executors as init containers, a TES task state may be incongruent with the Kubernetes pod state.

If you run kubectl get pods -n planetary-tasks, you may see task pods in one of the following states:

Pending - this state means the TES task is QUEUED.
Init:0/N - this state means the TES task is INITIALIZING and the inputs init container may be running.
Init:X/N (where X >= 1) - this state means the TES task is RUNNING and one of the executor init containers may be running.
Running - this state means the TES task is RUNNING and the outputs container is executing.
Completed - this state means the TES task is in the COMPLETED state.
Failed - this state means the TES task is likely in the EXECUTOR_ERROR or SYSTEM_ERROR state.

Running a TES task as a single pod has some performance benefits:

Fewer Kubernetes resources are created to e

Planetary

Install / Use

README

📚 About Planetary

⚠️ Security Notice

Architecture

Supported Cloud Storage

Task Execution