Skip to main content
Version: v0.13 ๐Ÿšง

Spec

The Spec represents the operational intentions that you aim to deliver using Kusion. These intentions are expected to contain all components throughout the DevOps lifecycle, including resources (workload, database, load balancer, etc.), dependencies, and policies. The Kusion module generators are responsible for converting all AppConfigurations and environment configurations into the Spec. Once the Spec is generated, the Kusion Engine takes charge of updating the actual infrastructures to match the Spec.

Purposeโ€‹

Single Source of Truthโ€‹

In Kusion's workflow, the platform engineer builds Kusion modules and provides environment configurations, application developers choose Kusion modules they need and deploy operational intentions to an environment with related environment configurations. They can also input dynamic parameters like the container image when executing the kusion generate command. So the final operational intentions include configurations written by application developers, environment configurations and dynamic inputs. Due to this reason, we introduce Spec to represent the SSoT(Single Source of Truth) of Kusion. It is the result of kusion generate which contains all operational intentions from different sources.

Consistencyโ€‹

Delivering an application to different environments with identical configurations is a common practice, especially for applications that require scalable distribution. In such cases, an immutable configuration package is helpful. By utilizing the Spec, all configurations and changes are stored in a single file. As the Spec is the input of Kusion, it ensures consistency across different environments whenever you execute Kusion with the same Spec file.

Rollback and Disaster Recoveryโ€‹

The ability to roll back is crucial in reducing incident duration. Rolling back the system to a previously validated version is much faster compared to attempting to fix it during an outage. We regard a validated Spec as a snapshot of the system and recommend storing the Spec in a version control system like Git. This enables better change management practices and makes it simpler to roll back to previous versions if needed. In case of a failure or outage, having a validated Spec simplifies the rollback process, ensuring that the system can be quickly recovered.

Exampleโ€‹

Below is an example Spec file generated from the quickstart demo application (more details can be found here).

resources:
- id: v1:Namespace:quickstart
type: Kubernetes
attributes:
apiVersion: v1
kind: Namespace
metadata:
creationTimestamp: null
name: quickstart
spec: {}
status: {}
extensions:
GVK: /v1, Kind=Namespace
- id: apps/v1:Deployment:quickstart:quickstart-default-quickstart
type: Kubernetes
attributes:
apiVersion: apps/v1
kind: Deployment
metadata:
creationTimestamp: null
labels:
app.kubernetes.io/name: quickstart
app.kubernetes.io/part-of: quickstart
name: quickstart-default-quickstart
namespace: quickstart
spec:
selector:
matchLabels:
app.kubernetes.io/name: quickstart
app.kubernetes.io/part-of: quickstart
strategy: {}
template:
metadata:
creationTimestamp: null
labels:
app.kubernetes.io/name: quickstart
app.kubernetes.io/part-of: quickstart
spec:
containers:
- image: kusionstack/kusion-quickstart:latest
name: quickstart
resources: {}
status: {}
dependsOn:
- v1:Namespace:quickstart
- v1:Service:quickstart:quickstart-default-quickstart-private
extensions:
GVK: apps/v1, Kind=Deployment
- id: v1:Service:quickstart:quickstart-default-quickstart-private
type: Kubernetes
attributes:
apiVersion: v1
kind: Service
metadata:
creationTimestamp: null
labels:
app.kubernetes.io/name: quickstart
app.kubernetes.io/part-of: quickstart
name: quickstart-default-quickstart-private
namespace: quickstart
spec:
ports:
- name: quickstart-default-quickstart-private-8080-tcp
port: 8080
protocol: TCP
targetPort: 8080
selector:
app.kubernetes.io/name: quickstart
app.kubernetes.io/part-of: quickstart
type: ClusterIP
status:
loadBalancer: {}
dependsOn:
- v1:Namespace:quickstart
extensions:
GVK: /v1, Kind=Service
secretStore: null
context: {}

From the example above, we can see that the Spec contains a list of resources required by the application. Each resource in the Spec needs to have a unique Kusion ID, resource type, resource attributes, resource dependencies, and some extension fields. In the extension field, you can declare information such as Kubernetes GVK, Terraform provider, etc.

Besides the resources, Spec also records the secretStore and context field in the corresponding workspace. The former can be used to access sensitive data stored in the cloud secrets management, while the latter can be used to declare the information such as Kubernetes kubeconfig file path or content, and Terraform providers' AK/SK. More information can be found here.

Apply with Spec Fileโ€‹

Kusion supports using the Spec file directly as input. Users can place the Spec file in the stack directory and execute kusion preview --spec-file spec.yaml and kusion apply --spec-file spec.yaml to preview and apply the resources.