Quick start for the saectl tool - Serverless App Engine - Alibaba Cloud Documentation Center

saectl is the command-line tool for Serverless App Engine (SAE). Use it to convert Kubernetes and Docker Compose YAML files to SAE format, then manage the full lifecycle of your SAE resources — namespaces, applications, Server Load Balancer (SLB) instances, and ConfigMaps.

Prerequisites

Before you begin, ensure that you have:

saectl installed and configured with an AccessKey ID, an AccessKey secret, and an application deployment region — see Install and configure the saectl tool

Quick start

The following commands show the minimal workflow to convert a Kubernetes YAML file and deploy an application to SAE:

saectl convert -f <k8s-file.yaml> -o <sae-file.yaml>  # Convert a Kubernetes YAML file to an SAE YAML file
saectl apply -f <sae-file.yaml>                        # Deploy the application
saectl get deployment <deployment-name>                # Check deployment status: PUBLISHING = in progress, RUNNING = ready

For a complete end-to-end example, see Deploy Nginx using saectl.

Convert a Kubernetes YAML file to an SAE YAML file

SAE YAML files follow SAE specifications, which differ from Kubernetes specifications. Use the convert command to generate an SAE-compliant file from an existing Kubernetes YAML file, then deploy with apply.

Convert the Kubernetes YAML file:

saectl convert -f <k8s-compliant-file.yaml> -o <sae-compliant-file.yaml>

Deploy the application:

saectl apply -f <sae-compliant-file.yaml>

If an error occurs, fix the SAE YAML file based on the error message and run apply again. Errors fall into two categories:
- Unsupported or differently formatted fields: Some fields in Kubernetes YAML files are not supported or have different format requirements in SAE YAML files. Delete or replace these fields after conversion. For supported fields and format requirements, see the other topics in this directory.
- Missing required fields: Some fields required by SAE YAML files may be absent from the Kubernetes YAML file. After conversion, a ${parameter_name} placeholder marks each missing field. Replace the placeholder with the actual value. For example, SAE requires a Virtual Private Cloud (VPC) when you define a namespace, but Kubernetes YAML files do not include this parameter. After conversion, the placeholder ${vpc-id} appears in the output:
```
apiVersion: v1
kind: Namespace
metadata:
  annotations:
    sae.aliyun.com/vpc-id: ${vpc-id}
  creationTimestamp: null
  labels:
    kubernetes.io/metadata.name: default
  name: nstest
spec: {}
status: {}
```

Important

If a Kubernetes YAML file defines multiple resources, separate them with the standard Kubernetes separator --- in a single file. saectl converts all resources in one batch. However, resources in the same file must not depend on a specific execution order. For example, if a Deployment and a Service that depends on that Deployment are in the same file, deployment fails because both resources are created simultaneously. Define order-dependent resources in separate files and apply them in sequence.

Deploy Nginx using saectl

This example deploys Nginx to SAE using two Kubernetes YAML files — a Deployment and a Service — and then cleans up.

Start with the following two Kubernetes YAML files: nginx-deployment.yaml:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx
  labels:
    app: nginx
spec:
  replicas: 1
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: registry.cn-beijing.aliyuncs.com/sae-serverless-demo/sae-demo:nginx-v1.23.4
        ports:
        - containerPort: 80
        resources:
          requests:
            cpu: "1"
            memory: "2Gi"

nginx-service.yaml:

apiVersion: v1
kind: Service
metadata:
  name: nginx
spec:
  allocateLoadBalancerNodePorts: true
  ports:
  - port: 80
    protocol: TCP
  selector:
    app: nginx
  type: LoadBalancer

Convert both files to SAE YAML format:

saectl convert -f nginx-deployment.yaml -o output-nginx-deployment.yaml
saectl convert -f nginx-service.yaml -o output-nginx-service.yaml

Deploy the Deployment and verify its status:

saectl apply -f output-nginx-deployment.yaml
saectl get deployment nginx  # STATE: PUBLISHING = in progress, RUNNING = ready

Wait until STATE is RUNNING before continuing.

Create the Service and get the public IP address:

saectl apply -f output-nginx-service.yaml
saectl get service internet-nginx -o wide  # EXTERNAL-IP: <pending> = creating, IP address = ready

Once EXTERNAL-IP shows an IP address, access the application:

curl http://<public-ip>:<port>

Clean up — delete the Deployment and Service when you are done:

saectl delete -f output-nginx-deployment.yaml  # The Service is deleted along with the Deployment

Convert a Docker Compose file to an SAE YAML file

To migrate an application from Docker Compose to SAE:

Convert the Docker Compose YAML file to a Kubernetes YAML file. For instructions, see the Kompose documentation.
Convert the Kubernetes YAML file to an SAE YAML file using saectl convert, as described above.

Manage namespaces

saectl supports creating, viewing, and deleting namespaces. Updating namespaces is not supported.

Create a namespace

Create a file named namespace.yaml with the following content:

apiVersion: v1
kind: Namespace
metadata:
  annotations:
    sae.aliyun.com/vpc-id: ${vpc-id}    # Replace with the VPC ID (format: vpc-xxxxxxxxxxxxxxxxxxxxx)
  name: ${namespace}                     # Replace with the namespace name
spec: {}

Apply the file to create the namespace:
```
saectl apply -f namespace.yaml
```

View namespaces

saectl get ns

Example output:

NAME        STATUS   REGION
default     Active   cn-beijing
testns      Active   cn-beijing

Field	Description
NAME	Namespace name. `default` is the default namespace.
STATUS	Namespace status. `Active` means the namespace is available.
REGION	Region where the namespace is located.

Delete a namespace

saectl delete ns <namespace>  # Replace <namespace> with the namespace name

Manage applications

saectl supports creating, viewing, updating, and deleting applications.

Create an application

Create a file named deployment.yaml with the following content:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: ${deployment-name}              # Replace with the application name
spec:
  replicas: 2                           # Number of application instances
  selector:
    matchLabels:
      sae.aliyun.com/app-name: ${deployment-name}
  template:
    metadata:
      labels:
        sae.aliyun.com/app-name: ${deployment-name}
    spec:
      containers:
      - name: main                      # Use "main" to avoid conflicts
        image: registry.openanolis.cn/openanolis/nginx:1.14.1-8.6

Apply the file to create the application in the default namespace:
```
saectl apply -f deployment.yaml
```

Check that the application is running:

saectl get deployment <deployment-name>  # STATE: RUNNING means the application is up

View the application's Pod instances:

saectl get pods -l sae.aliyun.com/app-name=<deployment-name>

View the application list

saectl get deployment -n <namespace>  # Omit -n to use the default namespace

Example output:

NAME         READY   AVAILABLE   TYPE    STATE     LANGUAGE   AGE
test-yaml    3/3     3           Image   RUNNING   java       6d1h
sc-c         2/2     2           Image   RUNNING   java       13d
sc-b         2/2     2           Image   RUNNING   java       13d
sc-a         1/1     1           Image   RUNNING   java       13d

Field	Description
NAME	Application name.
READY	Ready instances / target instances. An instance is ready when it passes the readiness probe check.
AVAILABLE	Currently running instances.
TYPE	Deployment method. `Image` means the application is deployed from a container image.
STATE	Application status. `RUNNING` means the application is running.
LANGUAGE	Technology stack of the application.
AGE	How long the application has been running.

View application details

Use get to view the YAML configuration or describe to view full details.

View application configuration

saectl get deployment <deployment-name> -o yaml -n <namespace>  # Omit -n to use the default namespace

View application details

saectl describe deployment <deployment-name> -n <namespace>  # Omit -n to use the default namespace

Update an application

Three commands are available: scale, edit, and apply.

Scale an application

saectl scale deployment <deployment-name> --replicas=<pod-num> -n <namespace>
# <pod-num>: the desired number of instances
# Omit -n to use the default namespace

Edit application configuration online

Open the application's YAML configuration in an editor:

saectl edit deployment <deployment-name> -n <namespace>  # Omit -n to use the default namespace

Modify the configuration, then save and close the file. The changes are applied automatically.

Apply updated configuration from a file

Modify deployment.yaml, then run:

saectl apply -f deployment.yaml

Delete an application

saectl delete deployment <deployment-name> -n <namespace>  # Omit -n to use the default namespace

Manage SLB instances

SLB instances correspond to the Service resource type in Kubernetes. saectl supports creating, viewing, updating, and detaching SLB instances.

Create a new SLB instance

Create a file named svc.yaml with the following content:

apiVersion: v1
kind: Service
metadata:
  name: internet-${deployment-name}     # "internet" = public network; use "intranet" for private network
                                        # Replace ${deployment-name} with the application name
spec:
  ports:
  - name: port-80
    port: 80                            # Port used to access the application
    protocol: TCP
    targetPort: 80                      # Port exposed by the container
  selector:
    sae.aliyun.com/app-name: ${deployment-name}

Apply the file to create the SLB instance:
```
saectl apply -f svc.yaml
```

Attach an application to an existing SLB instance

Create a file named svc.yaml with the sae.aliyun.com/loadbalancer-id annotation:

apiVersion: v1
kind: Service
metadata:
  annotations:
    sae.aliyun.com/loadbalancer-id: ${your-slb-id}   # Replace with the SLB ID
  name: internet-${deployment-name}                   # Replace ${deployment-name} with the application name
spec:
  ports:
  - name: port-80
    port: 80
    protocol: TCP
    targetPort: 80
  selector:
    sae.aliyun.com/app-name: ${deployment-name}

Apply the file:
```
saectl apply -f svc.yaml
```

View SLB instances

saectl get service -l sae.aliyun.com/app-name=<deployment-name> -n <namespace>
# Omit -l to list SLB instances for all applications
# Omit -n to use the default namespace

Example output:

NAME               TYPE           EXTERNAL-IP    PORT(S)   BOUND    AGE
internet-myapp     LoadBalancer   xxx.x.xx.xx    80/TCP    myapp    6d20h
intranet-myapp     LoadBalancer   xx.xx.xxx.xx   80/TCP    myapp    4d1h

Field	Description
NAME	Service name in the format `<network-type>-<application-name>`. `internet` = public network, `intranet` = private network.
TYPE	Service type. `LoadBalancer` means an SLB instance.
EXTERNAL-IP	IP address of the SLB instance.
PORT(S)	Port mapping of the SLB instance.
BOUND	Application that the SLB instance is attached to.
AGE	How long the service has existed.

View SLB instance details

saectl get service <service-name> -o yaml -n <namespace>  # Omit -n to use the default namespace

Update an SLB instance

Use edit to update online or apply to update from a file.

Edit SLB configuration online

Open the SLB configuration in an editor:

saectl edit service <service-name> -n <namespace>  # Omit -n to use the default namespace

Modify the configuration, then save and close the file. The changes are applied automatically.

Apply updated configuration from a file

Modify svc.yaml, then run:

saectl apply -f svc.yaml

Detach an SLB instance

saectl delete service <service-name> -n <namespace>  # Omit -n to use the default namespace

Manage ConfigMaps

saectl supports creating, viewing, updating, and deleting ConfigMaps. A ConfigMap stores configuration as key-value pairs, which you can reference as environment variables or mount as a file inside a container.

Create a ConfigMap

Create a file named cm.yaml with the following content:

apiVersion: v1
kind: ConfigMap
metadata:
  name: database-configmap   # ConfigMap name
  namespace: default         # Namespace where the ConfigMap is created
data:                        # Key-value pairs
  database: mysql
  database_uri: mysql://localhost:2309

Apply the file to create the ConfigMap:
```
saectl apply -f cm.yaml
```

View ConfigMaps

List ConfigMaps across all namespaces

saectl get configmap -A

Example output:

NAMESPACE   NAME            DATA   AGE
default     nacos           1      69d
test        test-config     2      10d

Field	Description
NAMESPACE	Namespace where the ConfigMap is located.
NAME	ConfigMap name.
DATA	Number of key-value pairs in the ConfigMap.
AGE	How long the ConfigMap has existed.

List ConfigMaps in a namespace

saectl get configmap -n <namespace>  # Omit -n to use the default namespace

View ConfigMap details

saectl get cm <cm-name> -o yaml -n <namespace>  # Omit -n to use the default namespace

Use a ConfigMap in a container

Reference as environment variables

Mount individual key-value pairs or all pairs as environment variables:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: test-configmap
  namespace: default
spec:
  replicas: 1
  selector:
    matchLabels:
      sae.aliyun.com/app-name: test-configmap
  template:
    metadata:
      creationTimestamp: null
      labels:
        sae.aliyun.com/app-name: test-configmap
    spec:
      containers:
      - args:
        - /home/admin/start.sh
        command:
        - /bin/bash
        env:                             # Reference individual key-value pairs
        - name: database                 # Environment variable name in the container
          valueFrom:
            configMapKeyRef:             # Value comes from the "database" key in database-configmap
              key: database
              name: database-configmap
        envFrom:                         # Reference all key-value pairs
        - configMapRef:                  # All pairs in other-configmap become environment variables
            name: other-configmap
        name: main
        image: registry.cn-shenzhen.aliyuncs.com/sae-serverless-demo/sae-demo:microservice-java-provider-v1.0
        imagePullPolicy: Always
        resources:
          limits:
            cpu: "2"
            memory: 4Gi
          requests:
            cpu: "2"
            memory: 4Gi
      restartPolicy: Always
      terminationGracePeriodSeconds: 10

Mount as a file

Mount a ConfigMap as a file at a specified path inside the container:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: test-configmap
  namespace: default
spec:
  replicas: 1
  selector:
    matchLabels:
      sae.aliyun.com/app-name: test-configmap
  template:
    metadata:
      labels:
        sae.aliyun.com/app-name: test-configmap
    spec:
      containers:
      - args:
        - /home/admin/start.sh
        command:
        - /bin/bash
        name: main
        image: registry.cn-shenzhen.aliyuncs.com/sae-serverless-demo/sae-demo:microservice-java-provider-v1.0
        imagePullPolicy: Always
        resources:
          limits:
            cpu: "2"
            memory: 4Gi
          requests:
            cpu: "2"
            memory: 4Gi
        volumeMounts:
        - mountPath: /tmp/nacos          # Path where the ConfigMap file is mounted
          name: my-volume
      volumes:
      - configMap:
          name: nacos-configmap          # ConfigMap to mount as my-volume
        name: my-volume
      restartPolicy: Always
      terminationGracePeriodSeconds: 10

Update a ConfigMap

Use edit to update online or apply to update from a file.

Edit a ConfigMap online

Open the ConfigMap in an editor:

saectl edit cm <cm-name> -n <namespace>  # Omit -n to use the default namespace

Modify the configuration, then save and close the file. The changes are applied automatically.

Apply updated configuration from a file

Modify cm.yaml, then run:

saectl apply -f cm.yaml

Delete a ConfigMap

saectl delete cm <cm-name> -n <namespace>  # Omit -n to use the default namespace

What's next

Install and configure the saectl tool
Explore the other topics in this directory for supported YAML fields and format requirements for SAE YAML files.