KusionStack

https://kusionstack.io/docs
Admin
KusionStack is a platform orchestrator that captures and orchestrates intents from different...
Tokens:75,164
Snippets:1,035
Trust Score:7.9
Update:5 months ago
Show doc for...
Tokens:
Raw
### Run Installation Script with Kubeconfig

Source: https://kusionstack.io/docs/getting-started/getting-started-with-kusion-server/install-kusion

Execute the installation script, providing your kubeconfig files as key-value pairs. The script uses these configurations to install Kusion.

```bash
./install-kusion.sh <kubeconfig_key1=kubeconfig_path1> <kubeconfig_key2=kubeconfig_path2> ...  
```

--------------------------------

### Get All Kubernetes Resources

Source: https://kusionstack.io/docs/user-guides/using-kusion-cli/llm-ops/inference

Execute this command to view all deployed Kubernetes resources in the 'example' namespace. It helps in verifying the status of pods, services, deployments, and replica sets.

```bash
➜  ~ kubectl get all -n example  
NAME                                           READY   STATUS    RESTARTS   AGE  
pod/example-dev-inference-5cf6c74574-7w92f     1/1     Running   0          2d6h  
pod/mynginx                                    1/1     Running   0          2d6h  
pod/ollama-infer-deployment-7c56845496-s5snb   1/1     Running   0          2d6h  

NAME                                   TYPE           CLUSTER-IP        EXTERNAL-IP     PORT(S)        AGE  
service/example-dev-inference-public   ClusterIP      192.168.116.121   <none>          80:32693/TCP         2d6h  
service/ollama-infer-service           ClusterIP      192.168.28.208    <none>          80/TCP         2d6h  

NAME                                      READY   UP-TO-DATE   AVAILABLE   AGE  
deployment.apps/example-dev-inference     1/1     1            1           2d6h  
deployment.apps/ollama-infer-deployment   1/1     1            1           2d6h  

NAME                                                 DESIRED   CURRENT   READY   AGE  
replicaset.apps/example-dev-inference-5cf6c74574     1         1         1       2d6h  
replicaset.apps/ollama-infer-deployment-7c56845496   1         1         1       2d6h  
```

--------------------------------

### Start Kusion Server

Source: https://kusionstack.io/docs/reference/commands/kusion-server

Use this command to start the Kusion server. Configure database connection, authentication, and other settings using flags.

```bash
kusion server --mode kcp --db_host localhost:3306 --db_user root --db_pass 123456
```

--------------------------------

### List Config Items with Example Comment

Source: https://kusionstack.io/docs/reference/commands/kusion-config-list

This example demonstrates how to list configuration items, including a comment indicating the purpose of the command. It's a practical way to check Kusion's settings.

```bash
# List config items
kusion config list
```

--------------------------------

### Local Backend Configuration Example

Source: https://kusionstack.io/docs/concepts/configuration

Example of a local backend configuration, specifying an optional path for storing files. If not set, the default path `${KUSION_HOME}` is used.

```json
# type local
{
    "path": "${local_path}" # type string, optional, the directory to store the files. If  not set, use the default path ${KUSION_HOME}. 
}

```

--------------------------------

### Download and Prepare Installation Script

Source: https://kusionstack.io/docs/getting-started/getting-started-with-kusion-server/install-kusion

Download the installation script from the KusionStack charts repository and make it executable. This script is used for installing Kusion with kubeconfig files.

```bash
curl -O https://raw.githubusercontent.com/KusionStack/charts/master/scripts/install-kusion.sh  
chmod +x install-kusion.sh  
```

--------------------------------

### Deliver Quickstart Application

Source: https://kusionstack.io/docs/getting-started/getting-started-with-kusion-cli/deliver-quickstart

Apply the quickstart application to your Kubernetes cluster using `kusion apply`. This command deploys the application and automatically forwards the specified port (8080) from local to the Kubernetes Service.

```bash
cd default && kusion apply --port-forward 8080
```

--------------------------------

### Initialize Application Directory

Source: https://kusionstack.io/docs/user-guides/using-kusion-cli/working-with-k8s/deploy-application

Create a new directory for your application and navigate into it. This is the starting point for defining your application's configuration.

```bash
# Create a new directory and navigate into it.   
mkdir simple-service && cd simple-service  
  

```

--------------------------------

### Kusion Project Structure

Source: https://kusionstack.io/docs/user-guides/using-kusion-cli/cloud-resources/expose-service

Example directory structure after initializing a Kusion project.

```bash
tree
.  
├── dev  
│   ├── kcl.mod  
│   ├── main.k  
│   └── stack.yaml  
└── project.yaml  
  
2 directories, 4 files

```

--------------------------------

### AppConfiguration Example for WordPress

Source: https://kusionstack.io/docs/reference/modules

Use AppConfiguration to define a WordPress application, including its service, containers, environment variables, resources, and database configuration. This model simplifies complex application setups.

```kcl
wordpress: ac.AppConfiguration {
    workload: service.Service {
        containers: {
            "wordpress": c.Container {
                image: "wordpress:latest"
                env: {
                    "WORDPRESS_DB_HOST": "secret://wordpress-db/hostAddress"
                    "WORDPRESS_DB_PASSWORD": "secret://wordpress-db/password"
                }
                resources: {
                    "cpu": "1"
                    "memory": "2Gi"
                }
            }
        }
        replicas: 2
        ports: [
            n.Port {
                port: 80
                public: True
            }
        ]
    }

    database: db.Database {
        type: "alicloud"
        engine: "MySQL"
        version: "5.7"
        size: 20
        instanceType: "mysql.n2.serverless.1c"
        category: "serverless_basic"
    }
}

```

--------------------------------

### Install Gettext using Homebrew

Source: https://kusionstack.io/docs/faq/install-error

Install the Gettext library using Homebrew to resolve 'Could not find libintl.dylib' errors on macOS.

```bash
brew install gettext
```

--------------------------------

### Destroy Application Resources

Source: https://kusionstack.io/docs/getting-started/getting-started-with-kusion-cli/deliver-quickstart

Remove the quickstart demo workload and all associated accessory resources using the `kusion destroy` command.

```bash
kusion destroy --yes

```

--------------------------------

### Install Kusion from Local Chart

Source: https://kusionstack.io/docs/getting-started/getting-started-with-kusion-server/install-kusion

Install the Kusion Helm chart from a locally cloned repository. This method is used after downloading the chart manually.

```bash
helm install kusion-release charts/kusion  
```

--------------------------------

### Example project.yaml with Kubernetes Namespace Extension

Source: https://kusionstack.io/docs/concepts/project/configuration

This example demonstrates how to configure the `kubernetesNamespace` extension in `project.yaml` to set a custom namespace for generated Kubernetes resources.

```yaml
name: example
extensions:
    - kind: kubernetesNamespace
      kubernetesNamespace:
        namespace: test

```

--------------------------------

### Define Project and Stack Configuration

Source: https://kusionstack.io/docs/user-guides/using-kusion-cli/llm-ops/inference

Example directory structure and configuration files for a Kusion project and stack. Includes project.yaml, stack.yaml, kcl.mod, and main.k.

```yaml
name: example

```

```yaml
name: default

```

```yaml
[dependencies]
kam = { git = "https://github.com/KusionStack/kam.git", tag = "0.2.0" }
service = {oci = "oci://ghcr.io/kusionstack/service", tag = "0.1.0" }
network = { oci = "oci://ghcr.io/kusionstack/network", tag = "0.2.0" }
inference = { oci = "oci://ghcr.io/kusionstack/inference", tag = "0.1.0-beta.4" }

```

--------------------------------

### Create Project in Current Directory

Source: https://kusionstack.io/docs/reference/commands/kusion-project-create

This example demonstrates creating a new project named after the current working directory. Ensure you are in an empty directory before running the command.

```bash
# Create a new project with the name of the current working directory  
mkdir my-project && cd my-project  
kusion project create  
```

--------------------------------

### Example Resource Graph Output

Source: https://kusionstack.io/docs/user-guides/using-kusion-cli/observability/resource-graph

This is an example of the resource graph output generated by the Kusion CLI. It details workload, dependency, and other resources with their respective attributes.

```text
Displaying resource graph in the project wordpress-rds-cloud...  
  
Workspace: demo  
  
Workload Resources:  
ID                                                      Kind                           Name                           CloudResourceID                Status  
apps/v1:Deployment:wordpress-rds-cloud:wordpress-rds-cl Kubernetes:apps/v1:Deployment  wordpress-rds-cloud/wordpress-                                Apply succeeded | Reconciled  
oud-dev-wordpress                                                                      rds-cloud-dev-wordpress  
  
Dependency Resources:  
ID                                                      Kind                           Name                           CloudResourceID                Status  
v1:Secret:wordpress-rds-cloud:wordpress-mysql-mysql     Kubernetes:v1:Secret           wordpress-rds-cloud/wordpress-                                Apply succeeded | Reconciled  
                                                                                       mysql-mysql  
v1:Service:wordpress-rds-cloud:wordpress-rds-cloud-dev- Kubernetes:v1:Service          wordpress-rds-cloud/wordpress-                                Apply succeeded | Reconciled  
wordpress-private                                                                      rds-cloud-dev-wordpress-privat  
                                                                                       e  
v1:Namespace:wordpress-rds-cloud                        Kubernetes:v1:Namespace        wordpress-rds-cloud                                           Apply succeeded | Reconciled  
  
Other Resources:  
ID                                                      Kind                           Name                           CloudResourceID                Status  
aliyun:alicloud:alicloud_db_connection:wordpress-mysql  alicloud:alicloud_db_connectio wordpress-mysql                rm-2zer0f93xy490fdzq:rm-2zer0f Apply succeeded | Reconciled  
                                                        n                                                             93xy490fdzqtf  
aliyun:alicloud:alicloud_db_instance:wordpress-mysql    alicloud:alicloud_db_instance  wordpress-mysql                rm-2zer0f93xy490fdzq           Apply succeeded | Reconciled  
aliyun:alicloud:alicloud_rds_account:wordpress-mysql    alicloud:alicloud_rds_account  wordpress-mysql                rm-2zer0f93xy490fdzq:root      Apply succeeded | Reconciled  
hashicorp:random:random_password:wordpress-mysql-mysql  custom:random_password                                                                       Apply succeeded  

```

--------------------------------

### Install Kusion via Homebrew

Source: https://kusionstack.io/docs/getting-started/getting-started-with-kusion-cli/install-kusion

Installs the Kusion CLI using the Homebrew package manager on macOS and Linux. Ensure you have Homebrew installed first.

```bash
# tap formula repository Kusionstack/tap  
brew tap KusionStack/tap  
  
# install Kusion   
brew install KusionStack/tap/kusion  
```

--------------------------------

### Install Kusion via Scoop

Source: https://kusionstack.io/docs/getting-started/getting-started-with-kusion-cli/install-kusion

Installs the Kusion CLI on Windows using the Scoop package manager. This requires adding the KusionStack bucket first.

```powershell
# add scoop bucket KusionStack  
scoop bucket add KusionStack https://github.com/KusionStack/scoop-bucket.git  
  
# install kusion  
scoop install KusionStack/kusion  
```

--------------------------------

### Install Latest Kusion via PowerShell

Source: https://kusionstack.io/docs/getting-started/getting-started-with-kusion-cli/install-kusion

Installs the latest version of the Kusion CLI on Windows using PowerShell. This command downloads and executes an installation script.

```powershell
# install Kusion, default latest version  
powershell -Command "iwr -useb https://www.kusionstack.io/scripts/install.ps1 | iex"  
```

--------------------------------

### Install Kusion with Kubeconfig and Optional Configurations

Source: https://kusionstack.io/docs/getting-started/getting-started-with-kusion-server/install-kusion

Install the Kusion Helm chart with encoded kubeconfig files and customize deployment parameters such as port, replicas, and database enablement.

```bash
# Install with kubeconfig and optional configurations  
helm install kusion-release kusionstack/kusion \  
--set kubeconfig.kubeConfigs.kubeconfig-0="$KUBECONFIG_CONTENT0" \  
--set kubeconfig.kubeConfigs.kubeconfig-1="$KUBECONFIG_CONTENT1" \  
--set server.port=8080 \  
--set server.replicas=3 \  
--set mysql.enabled=true \  
```

--------------------------------

### Define AppConfiguration for Quickstart Application

Source: https://kusionstack.io/docs/getting-started/getting-started-with-kusion-server/deliver-quickstart

This snippet defines an AppConfiguration for a quickstart application, specifying a service workload with a container and exposing port 8080 via a network accessory. This model simplifies Kubernetes resource management.

```kcl
ac.AppConfiguration {
    workload: service.Service {
        containers: {
            quickstart: c.Container {
                image: "kusionstack/kusion-quickstart:latest"
            }
        }
    }
    accessories: {
        "network": n.Network {
            ports: [
                n.Port {
                    port: 8080
                }
            ]
        }
    }
}
```

--------------------------------

### Apply CronJob from Scratch

Source: https://kusionstack.io/docs/user-guides/using-kusion-cli/working-with-k8s/job

Use this command to apply a CronJob when starting from a clean state. It shows the creation of a Namespace and the CronJob itself.

```bash
$ kusion apply  
 ✔︎  Generating Spec in the Stack dev...                                                                                                                                                                                                       
Stack: dev  ID                                                    Action  
* ├─     v1:Namespace:simple-service                               Create  
* └─     batch/v1:CronJob:simple-service:simple-service-dev-helloworld  Create  
  
  
? Do you want to apply these diffs? yes  
Start applying diffs ...  
 SUCCESS  Create v1:Namespace:simple-service success                                                                                                                                                                                                
 SUCCESS  Create batch/v1:CronJob:simple-service:helloworld-dev-helloworld success                                                                                                                                                                   
Create batch/v1:CronJob:simple-service:simple-service-dev-helloworld success [2/2] ██████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████ 100% | 0s  
Apply complete! Resources: 2 created, 0 updated, 0 deleted.  

```

--------------------------------

### Configure Application with MySQL Accessory in main.k

Source: https://kusionstack.io/docs/getting-started/getting-started-with-kusion-server/deliver-quickstart-with-db

Declare your application workload and configure a local MySQL database as an accessory. This setup allows Kusion to manage the database lifecycle and provide connection details to the application.

```kcl
import kam.v1.app_configuration as ac
import service
import service.container as c
import network as n
import mysql

# main.k declares the customized configuration codes for default-with-db stack. 
quickstart: ac.AppConfiguration {
    workload: service.Service {
        containers: {
            quickstart: c.Container {
                image: "kusionstack/kusion-quickstart:latest"
                env: {
                    "DB_HOST": "$(KUSION_DB_HOST_QUICKSTARTWITHDBDEFAULTWITHDBQU)"
                    "DB_USERNAME": "$(KUSION_DB_USERNAME_QUICKSTARTWITHDBDEFAULTWITHDBQU)"
                    "DB_PASSWORD": "$(KUSION_DB_PASSWORD_QUICKSTARTWITHDBDEFAULTWITHDBQU)"
                }
            }
        }
    }
    accessories: {
        "network": n.Network {
            ports: [
                n.Port {
                    port: 8080
                }
            ]
        }
        "mysql": mysql.MySQL {
            type: "local"
            version: "8.0"
        }
    }
}


```

--------------------------------

### Stack File with Kubernetes Namespace Extension

Source: https://kusionstack.io/docs/concepts/stack/configuration

Example `stack.yaml` file demonstrating how to specify a custom Kubernetes namespace for resource generation using the `kubernetesNamespace` extension.

```yaml
name: dev
extensions:
    - kind: kubernetesNamespace
      kubernetesNamespace:
        namespace: test

```

--------------------------------

### Kubernetes Resource Example in Kusion Spec

Source: https://kusionstack.io/docs/concepts/specs

This example demonstrates the structure of a Kubernetes resource within a Kusion Spec file, including its ID, type, attributes, and extensions.

```yaml
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: {}  

```

--------------------------------

### Workspace Configuration Example

Source: https://kusionstack.io/docs/concepts/workspace/overview

Defines modules, secret store, and context for a workspace. Use environment variables for sensitive data like access keys.

```yaml
# The platform configuration for Modules or KAMs.  
# For each Module or KAM, the configuration format is as below.   
# # ${module_identifier} or ${KAM_name}:  
# #   path: oci://ghcr.io/kusionstack/module-name # url of the module artifact  
# #   version: 0.2.0 # version of the module  
# #   configs:   
# #     default: # default configuration, applied to all projects  
# #       ${field1}: ${value1}  
# #       #{field2}: ${value2}  
# #       ...  
# #     ${patcher_name}: #patcher configuration, applied to the projects assigned in projectSelector  
# #       ${field1}: ${value1_override}  
# #       ...  
# #       projectSelector:  
# #       - ${project1_name}  
# #       - ${project2_name}  
# #       ...  
modules:  
   mysql:   
    path: oci://ghcr.io/kusionstack/mysql  
    version: 0.2.0  
    configs:  
      default:  
         cloud: alicloud  
         size: 20  
         instanceType: mysql.n2.serverless.1c  
         category: serverless_basic  
         privateRouting: false  
         subnetID: ${mysql_subnet_id}  
         databaseName: kusion  
      largeSize:  
        size: 50  
        projectSelector:  
        - foo  
        - bar  
      importDBInstance:   
        importedResources:   
          "aliyun:alicloud:alicloud_db_instance:wordpress-demo": "your-imported-resource-id"  
        projectSelector:   
        - baz  
  
secretStore:  
  provider:  
    aws:  
      region: us-east-1  
      profile: The optional profile to be used to interact with AWS Secrets Manager.  
  
context:   
   KUBECONFIG_PATH: $HOME/.kube/config  
   AWS_ACCESS_KEY_ID: ref://secrets-manager-name/key-for-ak  
   AWS_SECRET_ACCESS_KEY: ref://secrets-manager-name/key-for-sk  

```

--------------------------------

### Setup OSS Kusion Storage Backend

Source: https://kusionstack.io/docs/user-guides/using-kusion-cli/production-practice-case/collaborate-with-github-actions

Platform Engineers can use these commands to configure Alicloud OSS as a remote storage backend for Kusion CLI, enabling collaborative editing of application configurations. Ensure to replace placeholder AK/SK values.

```bash
# please replace the env with actual AK/SK  
export OSS_ACCESS_KEY_ID=LTAxxxxxxxxxxxxxx  
export OSS_ACCESS_KEY_SECRET=uUPxxxxxxxxxx  
  
# set up backend  
kusion config set backends.oss_test '{"type":"oss","configs":{"bucket":"kusion-test","endpoint":"oss-cn-shanghai.aliyuncs.com"}}'  
kusion config set backends.current oss_test  
```

--------------------------------

### Configure Workspace Modules

Source: https://kusionstack.io/docs/user-guides/using-kusion-cli/llm-ops/inference

Define the modules and their versions to be included in the workspace configuration. This example includes service, network, and inference modules.

```yaml
modules:
    service:
        path: oci://ghcr.io/kusionstack/service
        version: 0.2.0
        configs:
            default: {}
    network:
        path: oci://ghcr.io/kusionstack/network
        version: 0.2.0
        configs:
            default: {}
    inference:
        path: oci://ghcr.io/kusionstack/inference
        version: 0.1.0-beta.4
        configs:
            default: {}

```

--------------------------------

### Create a new stack in a specified target project directory

Source: https://kusionstack.io/docs/reference/commands/kusion-stack-create

Specify a target project directory to create the new stack. This example creates a 'dev' stack in '/dir/to/projects/my-project'.

```bash
kusion stack create dev --target /dir/to/projects/my-project
```

--------------------------------

### Instantiate Kusion AppConfiguration

Source: https://kusionstack.io/docs/configuration-walkthrough/overview

Define an application configuration using Kusion's AppConfiguration schema. This example shows how to specify workload details like container image and resources, as well as network accessories.

```kcl
import kam.v1.app_configuration as ac  
import service  
import service.container as c  
import network as n  
  
gocity: ac.AppConfiguration {  
    workload: service.Service {  
        containers: {  
            "gocity": c.Container {  
                image = "howieyue/gocity:latest"  
                resources: {  
                    "cpu": "500m"  
                    "memory": "512Mi"  
                }  
            }  
        }  
        replicas: 1  
    }  
    accessories: {  
        "network": n.Network {  
            ports: [  
                n.Port {  
                    port: 80  
                    public: True  
                }  
            ]  
        }  
    }  
}  

```

--------------------------------

### Define a Container with Nginx

Source: https://kusionstack.io/docs/reference/modules/developer-schemas/workload/job

This example shows how to define a container using the kam.workload.container library. It specifies the image, command, environment variables, and resource requirements. Import kam.workload.container as c.

```python
import kam.workload.container as c

web = c.Container {
    image:   "nginx:latest"
    command: ["/bin/sh", "-c", "echo hi"]
    env: {
        "name": "value"
    }
    resources: {
        "cpu": "2"
        "memory": "4Gi"
    }
}

```

--------------------------------

### Create a File During Container Initialization

Source: https://kusionstack.io/docs/configuration-walkthrough/workload

Use the `files` attribute to create a custom file and mount it to a specific path within the container when it starts. Specify the content and file mode.

```python
import kam.v1.app_configuration as ac
import service
import service.container as c

myapp: ac.AppConfiguration {
    workload: service.Service {
        containers: {
            "myapp": c.Container {
                image: "gcr.io/google-samples/gb-frontend:v5"
            }
            # ...
            # Creates a file during container startup
            files: {
                "/home/admin/my-file": c.FileSpec {
                    content: "some file contents"
                    mode: "0777"
                }
            }
        }
    }
}
```

--------------------------------

### Get a Kusion Config Item

Source: https://kusionstack.io/docs/reference/commands/kusion-config-get

Use this command to fetch the value of a registered configuration item. For example, to get the current backend configuration, use 'kusion config get backends.current'.

```bash
kusion config get backends.current
```

--------------------------------

### Import KCL Modules for Operational Rules

Source: https://kusionstack.io/docs/configuration-walkthrough/operational-rules

Import necessary KCL modules for defining application configurations and operational rules. This setup is required for the examples that follow.

```kcl
import kam.v1.app_configuration as ac  
import kam.v1.workload as wl  
import opsrule as o  

```

--------------------------------

### Define Alicloud Load Balancer Configuration

Source: https://kusionstack.io/docs/reference/modules/workspace-configs/networking/network

Example of configuring an Alicloud load balancer with specific labels and annotations. Ensure the module path and version are correctly specified.

```yaml
modules:
  path: oci://ghcr.io/kusionstack/network
  version: 0.2.0
  configs:
    default:
      type: alicloud
      labels:
        kusionstack.io/control: "true"
      annotations:
        service.beta.kubernetes.io/alibaba-cloud-loadbalancer-spec: slb.s1.small

```

--------------------------------

### Initialize a Demo Project

Source: https://kusionstack.io/docs/reference/commands/kusion-init

Use this command to initialize a demo project using the current directory's name. Ensure the target directory is empty before running.

```bash
mkdir quickstart && cd quickstart
kusion init
```

--------------------------------

### Install Prometheus Operator

Source: https://kusionstack.io/docs/user-guides/using-kusion-cli/observability/prometheus

Installs the Prometheus operator and necessary CRDs using a release bundle. Ensure you have `curl` and `jq` installed.

```bash
LATEST=$(curl -s https://api.github.com/repos/prometheus-operator/prometheus-operator/releases/latest | jq -cr .tag_name)
curl -sL https://github.com/prometheus-operator/prometheus-operator/releases/download/${LATEST}/bundle.yaml | kubectl create -f -
```

--------------------------------

### Sample Multi-Stack Project Directory Structure

Source: https://kusionstack.io/docs/configuration-walkthrough/overview

This is a sample directory structure for a multi-stack Kusion project, showing the organization of base configurations and stack-specific files.

```bash
multi-stack-project/  
├── README.md  
├── base  
│   └── base.k  
├── dev  
│   ├── kcl.mod  
│   ├── main.k  
│   └── stack.yaml  
├── prod  
│   ├── kcl.mod  
│   ├── main.k  
│   └── stack.yaml  
└── project.yaml  

```

--------------------------------

### Install Specified Kusion Version via PowerShell

Source: https://kusionstack.io/docs/getting-started/getting-started-with-kusion-cli/install-kusion

Installs a specific version of the Kusion CLI on Windows using PowerShell. The version is passed as a parameter to the installation script.

```powershell
# install Kusion of specified version 0.10.0  
powershell {"& { $(irm https://www.kusionstack.io/scripts/install.ps1) } -Version 0.11.0" | iex}  
```

--------------------------------

### kusion init Command Synopsis

Source: https://kusionstack.io/docs/reference/commands/kusion-init

The basic syntax for the kusion init command.

```bash
kusion init [flags]
```

--------------------------------

### kusion init Options

Source: https://kusionstack.io/docs/reference/commands/kusion-init

Available options for the kusion init command, including help and target directory specification.

```bash
kusion init [flags]

Options:
  -h, --help            help for init
  -t, --target string   specify the target directory
```

--------------------------------

### Install Kusion with Encoded Kubeconfig

Source: https://kusionstack.io/docs/getting-started/getting-started-with-kusion-server/install-kusion

Install the Kusion Helm chart by base64 encoding your kubeconfig files and passing them via the --set parameter. This method allows for remote installation.

```bash
# Base64 encode your kubeconfig files  
KUBECONFIG_CONTENT0=$(cat /path/to/your/kubeconfig-0 | base64 | tr -d '
')  
KUBECONFIG_CONTENT1=$(cat /path/to/your/kubeconfig-1 | base64 | tr -d '
')  
  
# Install with kubeconfig  
helm install kusion-release kusionstack/kusion \  
--set kubeconfig.kubeConfigs.kubeconfig-0="$KUBECONFIG_CONTENT0" \  
--set kubeconfig.kubeConfigs.kubeconfig-1="$KUBECONFIG_CONTENT1"  
```

--------------------------------

### Install Homebrew on macOS M1

Source: https://kusionstack.io/docs/faq/install-error

Use this command to install the arm version of Homebrew on macOS M1 systems if it's not already installed in /opt/homebrew. Ensure Homebrew is added to your PATH.

```bash
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"  
# add to path  
export PATH=/opt/homebrew/bin:$PATH  
```

--------------------------------

### Install Specified Kusion Version via Script

Source: https://kusionstack.io/docs/getting-started/getting-started-with-kusion-cli/install-kusion

Installs a specific version of the Kusion CLI by passing the version number as a parameter to the install script. The version should be the available tag without the 'v' prefix.

```bash
# install Kusion of specified version 0.11.0  
curl https://www.kusionstack.io/scripts/install.sh | sh -s 0.11.0  
```

--------------------------------

### KubeConfig Example Structure

Source: https://kusionstack.io/docs/getting-started/getting-started-with-kusion-server/install-kusion

This is an example structure for defining KubeConfig contents. Replace the placeholder text with your actual KubeConfig data.

```yaml
kubeConfigs:
  kubeconfig-0: |
      Please fill in your KubeConfig contents here.
  kubeconfig-1: |
      Please fill in your KubeConfig contents here.
```

--------------------------------

### Create and Verify Kusion Workspace

Source: https://kusionstack.io/docs/user-guides/using-kusion-cli/working-with-k8s/deploy-application

Use `kusion workspace create` to set up a new workspace and `kusion workspace list` to verify its creation. The `kusion workspace show` command displays the current configuration for a workspace.

```bash
~/playground$ touch ~/dev.yaml  
~/playground$ kusion workspace create dev -f ~/dev.yaml  
create workspace dev successfully  

```

```bash
~/playground$ kusion workspace list  
- default  
- dev  
~/playground$ kusion workspace show dev  
{}  

```

--------------------------------

### Get a Configuration Item

Source: https://kusionstack.io/docs/concepts/configuration

Use `kusion config get` to retrieve the value of a specific configuration item. Only registered items can be retrieved correctly.

```bash
# get a configuration item  
kusion config get backends.current  

```

--------------------------------

### Create New Kusion Project

Source: https://kusionstack.io/docs/user-guides/using-kusion-cli/production-practice-case/collaborate-with-github-actions

Developers can initiate a new project by creating a directory and then using the `kusion project create` command to set up the project structure.

```bash
# create a new project named quickstart  
mkdir quickstart && cd quickstart  
kusion project create  
  
```

--------------------------------

### Project and Stack Structure

Source: https://kusionstack.io/docs/user-guides/using-kusion-cli/cloud-resources/database

Illustrates the directory structure created after initializing a Kusion project and stack, showing key configuration files.

```bash
tree  
.  
├── dev  
│   ├── kcl.mod  
│   ├── main.k  
│   └── stack.yaml  
└── project.yaml  
  
2 directories, 4 files  
```

--------------------------------

### Initialize Kusion Module

Source: https://kusionstack.io/docs/concepts/module/develop-guide

Use this command to initialize a new Kusion module project. It downloads a scaffold repository and sets up the project structure.

```bash
kusion mod init <your-module-name>
```

--------------------------------

### Define Application Configuration (main.k)

Source: https://kusionstack.io/docs/user-guides/using-kusion-cli/working-with-k8s/deploy-application

The `main.k` file declares customized configurations for a specific stack, including defining an `AppConfiguration` instance with workload and accessory details.

```kcl
import kam.v1.app_configuration as ac
import service
import service.container as c
import network as n

helloworld: ac.AppConfiguration {
    workload: service.Service {
        containers: {
            "helloworld": c.Container {
                image = "kusionstack/kusion-quickstart:latest"
            }
        }
        replicas: 2
    }
    accessories: {
        "network": n.Network {
            ports: [
              n.Port {
                  port: 80
              }
            ]
        }
    }
}
```

--------------------------------

### Preview with specified work directory

Source: https://kusionstack.io/docs/reference/commands/kusion-preview

Use the -w or --workdir flag to specify the directory where Kusion should operate.

```bash
kusion preview -w /path/to/workdir
```

--------------------------------

### List All Configuration Items

Source: https://kusionstack.io/docs/concepts/configuration

Use `kusion config list` to display all Kusion configurations in YAML format.

```bash
# list all the Kusion configurations  
kusion config list  

```

--------------------------------

### Install Latest Kusion via Script

Source: https://kusionstack.io/docs/getting-started/getting-started-with-kusion-cli/install-kusion

Installs the latest version of the Kusion CLI using a curl command and a shell script. This method is suitable for macOS and Linux.

```bash
# install Kusion, default latest version  
curl https://www.kusionstack.io/scripts/install.sh | sh  
```

--------------------------------

### Get Backend Configuration

Source: https://kusionstack.io/docs/concepts/backend/managing-backends-with-cli

Use `kusion config get` to retrieve a whole backend configuration or a specific item. The key format is consistent with setting and unsetting operations.

```bash
# get a whole backend
kusion config get backends.s3_prod

```

```bash
# get a specified config item
kusion config get backends.s3_prod.configs.bucekt

```

--------------------------------

### Create Project in Specified Directory

Source: https://kusionstack.io/docs/reference/commands/kusion-project-create

Use the --target flag to specify a different directory for creating the new Kusion project. The specified directory must be empty.

```bash
kusion project create --target /dir/to/projects/my-project  
```

--------------------------------

### Initialize Kusion Project

Source: https://kusionstack.io/docs/getting-started/getting-started-with-kusion-cli/deliver-quickstart

Use `kusion init` to initialize a new Kusion project. This command sets up the basic project structure required for Kusion applications.

```bash
mkdir quickstart && cd quickstart

kusion init
```

--------------------------------

### Install Kusion with Registry Proxy

Source: https://kusionstack.io/docs/getting-started/getting-started-with-kusion-server/install-kusion

Install the Kusion Helm chart while specifying a registry proxy. This is useful for users in regions with potential network issues accessing official DockerHub images.

```bash
helm install kusion-release kusionstack/kusion --set registryProxy=docker.m.daocloud.io  
```

--------------------------------

### Install OpenSSL 1.1 using Homebrew

Source: https://kusionstack.io/docs/faq/install-error

Install OpenSSL version 1.1 via Homebrew to address macOS system SSL related errors, such as 'Openssl dylib library not found'.

```bash
brew install openssl@1.1
```

--------------------------------

### Kusion Mod Init Options

Source: https://kusionstack.io/docs/reference/commands/kusion-mod-init

Available options for the kusion mod init command, including help and template initialization.

```bash
-h, --help              help for init
```

```bash
      --template string   Initialize with specified template
```

--------------------------------

### Initialize Demo Project in a Specific Target Directory

Source: https://kusionstack.io/docs/reference/commands/kusion-init

Specify a different target directory for the demo project initialization using the --target flag. The target directory must be empty.

```bash
kusion init --target projects/my-demo-project
```

--------------------------------

### Apply Kusion Configuration

Source: https://kusionstack.io/docs/concepts/module/app-dev-guide

Execute this command to apply the defined Kusion configurations. It shows a preview of the changes to be made, including resource creation actions.

```bash
kusion apply  
 ✔︎  Generating Spec in the Stack dev...  
Stack: dev  
ID                                                     Action  
hashicorp:random:random_password:example-dev-kawesome  Create  
v1:Namespace:example                                   Create  
v1:Service:example:example-dev-kawesome                Create  
apps/v1:Deployment:example:example-dev-kawesome        Create  
  
  
Do you want to apply these diffs?:  
  > details  
Which diff detail do you want to see?:  
> all  
  hashicorp:random:random_password:example-dev-kawesome Create  
  v1:Namespace:example Create  
  v1:Service:example:example-dev-kawesome Create  
  apps/v1:Deployment:example:example-dev-kawesome Create  


```

--------------------------------

### Http Probe

Source: https://kusionstack.io/docs/reference/modules/developer-schemas/workload/service

Defines an action to perform an HTTP GET request against a container for health checks.

```APIDOC
## Schema Http

### Description
Http describes an action based on HTTP Get requests, used for health checks.

### Attributes
- **headers** (dict[str, str]) - Collection of custom headers to set in the request.
- **url** `required` (str) - The full qualified URL to send HTTP requests.

### Example
```python
import kam.workload.container.probe as p

httpProbe = p.Http {
    url: "http://localhost:80"
    headers: {
        "X-HEADER": "VALUE"
    }
}
```
```

--------------------------------

### Http Probe Schema

Source: https://kusionstack.io/docs/reference/modules/developer-schemas/workload/job

Defines an HTTP GET request action for probes, allowing custom headers and a target URL.

```APIDOC
## Schema Http

### Description
Http describes an action based on HTTP Get requests.

### Attributes
- **headers** (dict[str, str]): Collection of custom headers to set in the request.
- **url** `required` (str): The full qualified URL to send HTTP requests.

### Example Usage
```python
import kam.workload.container.probe as p

httpProbe = p.Http {
    url: "http://localhost:80"
    headers: {
        "X-HEADER": "VALUE"
    }
}
```
```

--------------------------------

### Create a New Project

Source: https://kusionstack.io/docs/reference/commands/kusion-project-create

Use this command to create a new Kusion project. The target directory must be empty. By default, it creates the project in the current working directory.

```bash
kusion project create  
```

--------------------------------

### Initialize Kusion Module

Source: https://kusionstack.io/docs/reference/commands/kusion-mod-init

Use this command to create a new Kusion module template in the current directory. Specify the module name as the first argument.

```bash
kusion mod init my-module
```

--------------------------------

### Configure Inference Schema

Source: https://kusionstack.io/docs/reference/modules/developer-schemas/inference

Example of how to configure the Inference schema with specific model and generation parameters. Ensure the 'inference.v1.infer' module is imported.

```yaml
import inference.v1.infer

accessories: {
    "inference@v0.1.0": infer.Inference {
        model: "llama3"
        framework: "Ollama"

        system: "You are Mario from super mario bros, acting as an assistant."
        template: "{{ if .System }}<|im_start|>system {{ .System }}<|im_end|> {{ end }}{{ if .Prompt }}<|im_start|>user {{ .Prompt }}<|im_end|> {{ end }}<|im_start|>assistant"

        top_k: 40
        top_p: 0.9
        temperature: 0.8

        num_predict: 128
        num_ctx: 2048
    }
}

```

--------------------------------

### Show Specified Workspace Configuration

Source: https://kusionstack.io/docs/reference/commands/kusion-workspace-show

To view the configuration of a specific workspace, provide its name as an argument. For example, to show the 'dev' workspace configuration.

```bash
kusion workspace show dev
```

--------------------------------

### Configure Application with MySQL Accessory

Source: https://kusionstack.io/docs/getting-started/getting-started-with-kusion-cli/deliver-quickstart

Update your `main.k` file to include the MySQL accessory, specifying its type and version. This configures the application to use a local MySQL instance.

```kcl
import kam.v1.app_configuration as ac
import service
import service.container as c
import network as n
import mysql

# main.k declares the customized configuration codes for default stack. 
quickstart: ac.AppConfiguration {
    workload: service.Service {
        containers: {
            quickstart: c.Container {
                image: "kusionstack/kusion-quickstart:latest"
                env: {
                    "DB_HOST": "$(KUSION_DB_HOST_QUICKSTART_DEFAULT_QUICKSTART_MYSQL)"
                    "DB_USERNAME": "$(KUSION_DB_USERNAME_QUICKSTART_DEFAULT_QUICKSTART_MYSQL)"
                    "DB_PASSWORD": "$(KUSION_DB_PASSWORD_QUICKSTART_DEFAULT_QUICKSTART_MYSQL)"
                }
            }
        }
    }
    accessories: {
        "network": n.Network {
            ports: [
                n.Port {
                    port: 8080
                }
            ]
        }
        "mysql": mysql.MySQL {
            type: "local"
            version: "8.0"
        }
    }
}


```

--------------------------------

### List All Projects in a Specified Backend

Source: https://kusionstack.io/docs/reference/commands/kusion-project-list

Use the --all flag with a specified backend to list projects across all available workspaces.

```bash
kusion project list --backend default --all
```

--------------------------------

### Uninstall Kusion Helm Release

Source: https://kusionstack.io/docs/getting-started/getting-started-with-kusion-server/install-kusion

Uninstall the Helm release named 'kusion-release' from the 'kusion' namespace. This command removes all resources associated with the Kusion installation.

```bash
helm uninstall kusion-release  
```

--------------------------------

### Define Basic Authentication Secret

Source: https://kusionstack.io/docs/reference/modules/developer-schemas/internal/secret

Example of how to define a basic authentication secret using the Secret schema. This is useful for storing username and password pairs.

```python
import kam.workload.secret as sec

basicAuth = sec.Secret {
    type: "basic"
    data: {
        "username": ""
        "password": ""
    }
}

```

--------------------------------

### KCL PostgreSQL Accessory Configuration (AWS)

Source: https://kusionstack.io/docs/configuration-walkthrough/databse

Define a PostgreSQL accessory within an AppConfiguration using KCL. This example configures a cloud-based PostgreSQL instance.

```kcl
pgadmin: ac.AppConfiguration {
    # ...
    accessories: {
        "postgres": postgres.PostgreSQL {
            type:   "cloud"
            version: "14.0"
        }
    }
}
```

--------------------------------

### Kusion Config Help Option

Source: https://kusionstack.io/docs/reference/commands/kusion-config

Provides help information for the config command.

```bash
  -h, --help   help for config  
```

--------------------------------

### KCL MySQL Accessory Configuration (AWS)

Source: https://kusionstack.io/docs/configuration-walkthrough/databse

Define a MySQL accessory within an AppConfiguration using KCL. This example specifies a cloud-based MySQL instance.

```kcl
wordpress: ac.AppConfiguration {
    # ...
    accessories: {
        "mysql": mysql.MySQL {
            type:   "cloud"
            version: "8.0"
        }
    }
}
```

--------------------------------

### Initialize Kusion Module at Specified Path

Source: https://kusionstack.io/docs/reference/commands/kusion-mod-init

This command initializes a Kusion module at a specific directory path. Provide the module name and the target path.

```bash
kusion mod init my-module ./modules
```

--------------------------------

### Kusion Project Structure

Source: https://kusionstack.io/docs/user-guides/using-kusion-cli/working-with-k8s/deploy-application

Understand the default directory structure created by `kusion init`, including configuration files for projects and stacks.

```text
simple-service/
.
├── dev
│   ├── kcl.mod
│   ├── main.k
│   └── stack.yaml
└── project.yaml

2 directories, 4 files
```

--------------------------------

### Show resource details with specified backend

Source: https://kusionstack.io/docs/reference/commands/kusion-resource-show

Use this command to show details of a resource using a specific backend. Supported backends include 'local', 'oss', and 's3'.

```bash
kusion resource show --id=hashicorp:viettelcloud:viettelcloud_db_instance:example-mysql --backend=local
```

--------------------------------

### Conditional Statements in KCL

Source: https://kusionstack.io/docs/configuration-walkthrough/kcl-basics

An example of using a conditional expression to set the 'replicas' value based on the 'cpu' resource. Imports are required for type definitions.

```kcl
import kam.v1.app_configuration as ac  
import service  
import service.container as c  

myapp: ac.AppConfiguration {
    workload: service.Service {
        containers: {
            "myapp": c.Container {
                image: "<no value>"
                resources: {
                    "cpu": "500m"
                    "memory": "512Mi"
                }
            }
        }
        replicas: 1 if containers.myapp.resources.cpu == "500m" else 2
    }
}

```

--------------------------------

### Declare Dependency Packages in kcl.mod

Source: https://kusionstack.io/docs/getting-started/getting-started-with-kusion-server/deliver-quickstart

Declare the necessary Kusion Module dependencies for your project in the `default/kcl.mod` file. Ensure the module versions are compatible with your Kusion installation.

```ini
[dependencies]
kam = { git = "git://github.com/KusionStack/kam", tag = "0.2.2" }
network = { oci = "oci://ghcr.io/kusionstack/network", tag = "0.3.0" }
service = { oci = "oci://ghcr.io/kusionstack/service", tag = "0.2.1" }
```

--------------------------------

### List All Kusion Config Items

Source: https://kusionstack.io/docs/reference/commands/kusion-config-list

Use this command to view all available configuration items and their current values. This is useful for understanding the Kusion environment's settings.

```bash
kusion config list
```

--------------------------------

### Search Available Helm Chart Versions

Source: https://kusionstack.io/docs/getting-started/getting-started-with-kusion-server/install-kusion

Update the Helm repository and search for all available versions of the kusionstack/kusion chart. This helps in selecting a specific version for installation or upgrade.

```bash
helm repo update  
helm search repo kusionstack/kusion --versions  
```

--------------------------------

### Define a Probe with HTTP Handler

Source: https://kusionstack.io/docs/reference/modules/developer-schemas/internal/container/probe

Use this to define a probe that checks container health via HTTP GET requests. Specify the path and initial delay for the check.

```kcl
import kam.workload.container.probe as p

probe = p.Probe {
    probeHandler: p.Http {
        path: "/healthz"
    }
    initialDelaySeconds: 10
}

```

--------------------------------

### Initialize Kusion Project

Source: https://kusionstack.io/docs/user-guides/using-kusion-cli/cloud-resources/expose-service

Initialize a new Kusion project within the current directory. This command is typically run after creating a workspace.

```bash
# Create a new directory and navigate into it. 
mkdir nginx && cd nginx

# Initialize the demo project with the name of the current directory. 
kusion init

```

--------------------------------

### Create Kusion Workspace

Source: https://kusionstack.io/docs/user-guides/using-kusion-cli/cloud-resources/database

Initiate a Kusion workspace for the 'dev' stack using a specified workspace configuration file.

```bash
kusion workspace create dev -f workspace.yaml  
```

--------------------------------

### Verify Kubernetes Resource Health Policy

Source: https://kusionstack.io/docs/user-guides/using-kusion-cli/working-with-k8s/health-policy

Use kubectl to get the YAML definition of a Kubernetes resource. This helps in verifying if the resource meets the conditions defined in your health policy.

```bash
kubectl get -n quickstart deployment quickstart-default-quickstart -o yaml  

```

--------------------------------

### Verify Container Attributes in Deployment

Source: https://kusionstack.io/docs/user-guides/using-kusion-cli/working-with-k8s/container

Use kubectl to get the deployment in YAML format and verify that the container attributes, such as environment variables, image, and resource limits, have been updated as expected.

```bash
$ kubectl get deployment -n simple-service -o yaml  
...  
    template:  
      ...  
      spec:  
        containers:  
        - env:  
          - name: env1  
            value: VALUE  
          - name: env2  
            value: VALUE2  
          image: gcr.io/google-samples/gb-frontend:v4  
          imagePullPolicy: IfNotPresent  
          name: helloworld  
          readinessProbe:  
            failureThreshold: 3  
            httpGet:  
              host: localhost  
              path: /  
              port: 80  
              scheme: HTTP  
            initialDelaySeconds: 10  
            periodSeconds: 10  
            successThreshold: 1  
            timeoutSeconds: 1  
          resources:  
            limits:  
              cpu: 500m  
              memory: 512M  
...  


```

--------------------------------

### List Projects in Current Backend and Workspace

Source: https://kusionstack.io/docs/reference/commands/kusion-project-list

Use this command to view projects in the default backend and workspace. This is the most basic usage.

```bash
kusion project list
```

--------------------------------

### Example Health Policy for Kubernetes Deployment

Source: https://kusionstack.io/docs/user-guides/using-kusion-cli/working-with-k8s/health-policy

Define a custom health policy in `~/dev.yaml` to check if a Kubernetes Deployment has 1 replica and if its observed generation matches the current generation.

```yaml
modules:  
    service:  
        configs:  
            default:  
                healthPolicy:  
                    health.kcl: |  
                        assert res.metadata.generation == res.status.observedGeneration  
                        assert res.status.replicas == 1  
```

--------------------------------

### Example Kubernetes Deployment Manifest

Source: https://kusionstack.io/docs/user-guides/using-kusion-cli/working-with-k8s/k8s-manifest

A sample Kubernetes Deployment YAML defining an Nginx deployment with 3 replicas in the 'test' namespace. This manifest can be applied using the `k8s_manifest` module.

```yaml
apiVersion: apps/v1  
kind: Deployment  
metadata:  
  name: nginx-deployment  
  namespace: test  
  labels:  
    app: nginx  
spec:  
  replicas: 3  
  selector:  
    matchLabels:  
      app: nginx  
  template:  
    metadata:  
      labels:  
        app: nginx  
    spec:  
      containers:  
      - name: nginx  
        image: nginx:1.14.2  
        ports:  
        - containerPort: 80  

```
Tokens:
Raw