Kusion Documentation

Kusion is an intent-driven Platform Orchestrator designed to sit at the core of an Internal Developer Platform (IDP). It enables app-centric development by allowing developers to write a single application specification called an AppConfiguration.

This AppConfiguration defines the workload and all resource dependencies without requiring environment-specific values. Kusion then ensures all necessary components are provided for the application to run. It serves two primary roles:

1. Platform Engineers: Use Kusion to create shared modules and workspace definitions that codify security, compliance, and finance requirements.
2. Application Developers: Leverage those modules and workspaces to deploy applications using a self-service model, focusing on building applications rather than managing underlying infrastructure.

Kusion is a Platform Orchestrator for Internal Developer Platforms that delivers user intentions to Kubernetes, Clouds, and On-Premise resources. The kusion command serves as the primary entrypoint for managing stacks, building modules, and deploying resources.

Common workflows include:

• Initializing projects with kusion init.
• Building Kusion modules with kusion build.
• Previewing changes with kusion preview.
• Applying operational intent with kusion apply.
• Destroying resources with kusion destroy.

kusion [flags]

A Kusion module is a reusable building block designed by platform engineers to provide specific capabilities to an application.

Key characteristics:

• Independent Unit: Provides specific business semantics (e.g., a database, monitoring, or network access).
• Resource Composition: Consists of one or multiple infrastructure resources (K8s or Terraform), but is more than just a collection of unrelated resources.
• Non-nested: Modules should not have dependencies on or be nested within each other.
• Distinction: An AppConfiguration is NOT a Kusion Module.

Modules are used to attach 'accessories' to a workload or to define the workload itself.

A workspace is a logical concept in Kusion representing a deployment target for stacks.

Workspaces are typically managed by platform engineers and contain configurations that application developers should not need to manage. A single workspace can be reused by multiple stacks belonging to different projects.

Introduced in v0.14.0, Kusion Server is a long-running service that provides the same functionalities as the Kusion CLI but adds centralized management capabilities.

Key features include:

• Centralized Management: Manages instances of Projects, Stacks, Workspaces, and Runs via a Developer Portal.
• Metadata & Visualization: Manages application metadata and provides visualized application resource graphs.
• Integration: Provides a set of RESTful APIs for integration with other systems.

Note: Kusion Server requires a properly configured kubeconfig as it needs access to a Kubernetes cluster to function.

A Workspace is a logical concept representing a deployment target (e.g., dev, staging, prod, or cloud vendors like AWS). It contains a collection of application-independent configurations, including:

• Module inputs: Configurations for building resource intent.
• Runtime configs: Settings for execution environments like kubernetes or terraform.
• Backend configs: Settings for state and intent storage (e.g., s3, local).
• Secrets: Sensitive data like kubeconfig or provider credentials (e.g., AWS_ACCESS_KEY_ID), which should be managed via environment variables.

Key Constraint: A stack must be linked with exactly one workspace, and the stack name must match the workspace name it is deploying to.

Introduced in Kusion v0.14.0, the Kusion Server is a long-running service that provides functionality similar to the Kusion CLI, but with enhanced capabilities for managing application metadata and visualized application resource graphs.

Key features of Kusion Server:

• Centralized Management: Manages examples of projects, stacks, workspaces, and runs.
• Integration: Provides a RESTful API set to interact with the Developer Portal and other external systems.

Kusion facilitates a clear separation of concerns between Platform Engineers and Application Developers to reduce cognitive load and improve organizational efficiency.

• Application Developers: Focus on business logic. They declare the infrastructure services they need (e.g., a MySQL database or public internet access) using developer-friendly, high-level abstractions. They do not manage low-level infrastructure details.
• Platform Engineers: Focus on infrastructure standardization. They build and maintain Kusion modules that act as building blocks (e.g., database, networking, monitoring). These modules hide infrastructure complexity and ensure compliance with organizational standards.

By using Kusion modules, developers can self-service their requirements while platform engineers maintain control over the underlying implementation and standardization.

The Build step renders dynamic AppConfiguration code into static infrastructure resource configuration data, represented by the Spec model.

Why the Build step is necessary:

• Stability: Unlike dynamic code, which can produce different results based on execution parameters or external services, Spec is static and serves as the single Source of Truth.
• Safety & Validation: The Build step detects syntax and semantic errors in the configuration code before any infrastructure is touched. It also enables policy enforcement and auditing on the static Spec data.
• Performance: Pre-building the configuration reduces the execution load and time required during the Apply step.

Spec acts as an artifact. Once its safety is guaranteed, it is ready to be consumed by infrastructure runtimes in the next step.

Kusion uses three primary logical concepts to organize and isolate application deployments:

• Workspace: A logical target for deployment. Workspaces are typically grouped by SDLC phases (e.g., dev, staging, prod) or cloud vendors (e.g., AWS, Azure, Aliyun).
• Project: A logical concept used to bundle application configurations together.
• Stack: The smallest operational unit that can be configured and deployed independently. A stack provides a mechanism to isolate multiple deploys of the same application. Note: The name of each stack must match a specific workspace name.