Manage applications using the saectl tool-Serverless App Engine(SAE)-阿里云帮助中心

The saectl tool lets you manage the full lifecycle of SAE applications from the command line using Kubernetes-style YAML configuration files and kubectl-compatible commands. This topic covers creating, viewing, updating, and deleting applications, along with the complete K8s YAML configuration reference for SAE Deployments.

Prerequisites

Before you begin, install the saectl tool and configure your AccessKey ID, AccessKey Secret, and application deployment region. For more information, see Install and configure the saectl tool.

Create applications

SAE supports two deployment methods: image-based and code package-based (JAR or WAR packages). Both use saectl apply -f application.yaml to create the application.

Deploy an application using an image

Create an application.yaml configuration file. The following example shows a complete image-based deployment. For a description of each field, see K8s YAML configuration reference.

apiVersion: apps/v1
kind: Deployment
metadata:
  annotations:
    # Application version
    sae.aliyun.com/new-sae-version: pro
    # Application language
    sae.aliyun.com/language: java
    # Kafka log collection configuration
    sae.aliyun.com/log-kafka-config: '{"kafkaEndpoint":"10.0.X.XXX:XXXX,10.0.X.XXX:XXXX,10.0.X.XXX:XXXX","kafkaInstanceId":"alikafka_****","kafkaConfigs":[{"logType":"file_log","logDir":"/tmp/a.log","kafkaTopic":"test2"},{"logType":"stdout","logDir":"","kafkaTopic":"test"}]}'
    # SLS log collection configuration
    sae.aliyun.com/log-sls-config: '[{"logDir":"","logType":"stdout"},{"logDir":"/tmp/a.log"}]'
    # Nacos registry
    sae.aliyun.com/micro-registration: "2"
    # Registry configuration
    sae.aliyun.com/micro-registration-config: '{"instanceId":"mse_xxxxxxx","namespace":"xxxxxxxxxxxx"}'
    # NAS mount
    sae.aliyun.com/nas-mount: '[{"mountPath":"/test1","readOnly":false,"nasId":"nasId1","mountDomain":"nasId1.cn-shenzhen.nas.aliyuncs.com","nasPath":"/test1"},{"nasId":"nasId2","mountDomain":"nasId2.cn-shenzhen.nas.aliyuncs.com","readOnly":false,"nasPath":"/test2","mountPath":"/test2"}]'
    # OSS mount
    sae.aliyun.com/oss-mount: '{"ossAkId":"******","ossAkSecret":"******","ossMountDescs":[{"bucketName":"bucket","bucketPath":"/","mountPath":"/tmp"}]}'
    # K8s Service discovery configuration
    sae.aliyun.com/pvtz-discovery-svc: '{"serviceName":"gateway-cn-beijing-demo","namespaceId":"cn-beijing:front","portAndProtocol":{"18012":"TCP"},"enable":true,"portProtocols":[{"port":18012,"protocol":"TCP"}]}'
    # JDK runtime
    sae.aliyun.com/runtime: Open JDK 8
    # Security group
    sae.aliyun.com/security-group-id: sg-xxxxxxx
    # Deployment method: Image for image-based deployment
    sae.aliyun.com/type: Image
    # VPC ID
    sae.aliyun.com/vpc-id: vpc-xxxxxxxx
    # vSwitch list
    sae.aliyun.com/vswitch-list: vsw-xxxxxxx
    # For end-to-end canary release: baseline application name
    sae.aliyun.com/base-app-name: base-app
    # For end-to-end canary release: grayscale label
    sae.aliyun.com/serviceTags: '{"alicloud.service.tag":"g1"}'
    # Enable application monitoring
    sae.aliyun.com/enable-new-arms: 'true'
  name: test-yaml        # Application name
  namespace: default     # Namespace ID
spec:
  replicas: 2            # Number of container instances
  selector:
    matchLabels:
      sae.aliyun.com/app-name: test-yaml   # Application name (static format)
  strategy:
    rollingUpdate:
      maxSurge: 0        # Static field
      maxUnavailable: 1  # Maximum unavailable instances during rolling update
    type: RollingUpdate  # Static field
  template:
    metadata:
      labels:
        sae.aliyun.com/app-name: test-yaml    # Application name (static format)
        msePilotAutoEnable: "on"              # Enable microservice governance ("off" to disable)
        mse.lossless.enable: 'true'           # Enable graceful start ("false" to disable)
        mse.lossless.delayTime: '30'          # Delayed registration duration (seconds). If non-zero, configure a business readiness probe.
        mse.lossless.warmupTime: '60'         # Traffic warmup duration (seconds)
        mse.lossless.notice: 'true'           # Enable graceful shutdown notification ("false" to disable)
    spec:
      containers:
      - args:
        - /home/admin/start.sh               # Start command parameters
        command:
        - /bin/bash                          # Start command. Valid values: /bin/sh, /bin/bash
        env:                                 # Container environment variables
        - name: test
          value: "123"
        - name: my-office
          valueFrom:
            configMapKeyRef:
              key: office
              name: my-config
        # Container image. Can be from Container Registry (ACR), a public registry, or a self-built private registry.
        # Make sure the application network can access the registry and has the required permissions.
        image: registry.cn-shenzhen.aliyuncs.com/sae-serverless-demo/sae-demo:microservice-java-provider-v1.0
        imagePullPolicy: Always              # Static field
        livenessProbe:                       # Liveness probe
          failureThreshold: 1               # Unhealthy threshold (times)
          initialDelaySeconds: 1            # Delay before first check (seconds)
          periodSeconds: 5                  # Check interval (seconds)
          tcpSocket:
            port: 18081
          timeoutSeconds: 3                 # Timeout (seconds)
        name: main                          # Static field
        readinessProbe:                     # Business readiness probe
          failureThreshold: 1
          initialDelaySeconds: 1
          periodSeconds: 5
          successThreshold: 1              # Healthy threshold (times)
          tcpSocket:
            port: 18081
          timeoutSeconds: 5
        # Container instance specifications. Limits and requests must have the same configuration.
        resources:
          limits:
            cpu: "2"
            memory: 4Gi
          requests:
            cpu: "2"
            memory: 4Gi
        volumeMounts:                        # Mount ConfigMap items as files
        - mountPath: /tmp/myconfig/name
          name: my-config
          subPath: name                     # Key name when mounting a specific ConfigMap entry
        - mountPath: /tmp/otherconfig
          name: other-config
      hostAliases:                           # Hosts entries
      - hostnames:
        - locahost2
        ip: 127.0.0.2
      - hostnames:
        - localhost
        ip: 127.0.0.1
      restartPolicy: Always                  # Static field
      terminationGracePeriodSeconds: 10      # Graceful shutdown timeout (seconds)
      volumes:                               # Associate volumes with ConfigMaps
      - configMap:
          name: my-config
        name: my-config
      - configMap:
          name: other-config
        name: other-config

In the directory where application.yaml is located, run:
```
saectl apply -f application.yaml
```

Deploy an application using a code package

Code package deployment adds an upload step before applying the configuration. The key difference from image deployment is that spec.template.spec.containers[].image must be set to the static value mock-image.

Upload the code package using one of the following methods:
Upload to SAE
In the directory where the code package is located, run:
```
saectl upload <package-filename>
```
The output returns the code package URL. Record this URL for the next step.
```
PackageUrl: https://sae-oss-cn-hangzhou.oss-cn-hangzhou.aliyuncs.com/apps/K8S_APP_ID/<account_id>/<package_uuid>/hello-sae.jar
```
Upload to an OSS bucket
Upload the code package to an existing OSS bucket and record the URL. For more information, see OSS quick start.

Create an application.yaml file. Set sae.aliyun.com/package-url to the URL from the previous step, and set image to the static value mock-image.

Important

Both of the following fields are required for code package deployment: - metadata.annotations.sae.aliyun.com/package-url: the URL of the uploaded code package - spec.template.spec.containers[].image: must be set to mock-image

apiVersion: apps/v1
kind: Deployment
metadata:
  annotations:
    # Application version
    sae.aliyun.com/new-sae-version: pro
    # Application language
    sae.aliyun.com/language: java
    # Kafka log collection configuration
    sae.aliyun.com/log-kafka-config: '{"kafkaEndpoint":"10.0.X.XXX:XXXX,10.0.X.XXX:XXXX,10.0.X.XXX:XXXX","kafkaInstanceId":"alikafka_****","kafkaConfigs":[{"logType":"file_log","logDir":"/tmp/a.log","kafkaTopic":"test2"},{"logType":"stdout","logDir":"","kafkaTopic":"test"}]}'
    # SLS log collection configuration
    sae.aliyun.com/log-sls-config: '[{"logDir":"","logType":"stdout"},{"logDir":"/tmp/a.log"}]'
    # Nacos registry
    sae.aliyun.com/micro-registration: "2"
    # Registry configuration
    sae.aliyun.com/micro-registration-config: '{"instanceId":"mse_xxxxxxx","namespace":"xxxxxxxxxxxx"}'
    # NAS mount
    sae.aliyun.com/nas-mount: '[{"mountPath":"/test1","readOnly":false,"nasId":"nasId1","mountDomain":"nasId1.cn-shenzhen.nas.aliyuncs.com","nasPath":"/test1"},{"nasId":"nasId2","mountDomain":"nasId2.cn-shenzhen.nas.aliyuncs.com","readOnly":false,"nasPath":"/test2","mountPath":"/test2"}]'
    # OSS mount
    sae.aliyun.com/oss-mount: '{"ossAkId":"******","ossAkSecret":"******","ossMountDescs":[{"bucketName":"bucket","bucketPath":"/","mountPath":"/tmp"}]}'
    # K8s Service discovery configuration
    sae.aliyun.com/pvtz-discovery-svc: '{"serviceName":"gateway-cn-beijing-demo","namespaceId":"cn-beijing:front","portAndProtocol":{"18012":"TCP"},"enable":true,"portProtocols":[{"port":18012,"protocol":"TCP"}]}'
    # JDK runtime
    sae.aliyun.com/runtime: Open JDK 8
    # Security group
    sae.aliyun.com/security-group-id: sg-xxxxxxx
    # Deployment method: FatJar for JAR packages, War for WAR packages
    sae.aliyun.com/type: FatJar
    # Tomcat version (for WAR packages)
    sae.aliyun.com/web-container: apache-tomcat-7.0.91
    # Timezone
    sae.aliyun.com/timezone: Asia/Shanghai
    # Package version number
    sae.aliyun.com/package-version: <version>
    # Code package URL (from step 1)
    sae.aliyun.com/package-url: <package-url>
    # VPC ID
    sae.aliyun.com/vpc-id: vpc-xxxxxxxx
    # vSwitch list
    sae.aliyun.com/vswitch-list: vsw-xxxxxxx
    # For end-to-end canary release: baseline application name
    sae.aliyun.com/base-app-name: base-app
    # For end-to-end canary release: grayscale label
    sae.aliyun.com/serviceTags: '{"alicloud.service.tag":"g1"}'
    # Enable application monitoring
    sae.aliyun.com/enable-new-arms: 'true'
    # HSF runtime environment version
    sae.aliyun.com/edas-container-version: 3.5.3
    # JAR package start command parameters
    sae.aliyun.com/jar-start-args: custom-args
    # JAR package JVM options
    sae.aliyun.com/jar-start-options: -Xms4G -Xmx4G
    # WAR package JVM options
    sae.aliyun.com/war-start-options: -XX:+UseG1GC
  name: test-yaml        # Application name
  namespace: default     # Namespace ID
spec:
  replicas: 2            # Number of container instances
  selector:
    matchLabels:
      sae.aliyun.com/app-name: test-yaml   # Application name (static format)
  strategy:
    rollingUpdate:
      maxSurge: 0        # Static field
      maxUnavailable: 1  # Maximum unavailable instances during rolling update
    type: RollingUpdate  # Static field
  template:
    metadata:
      labels:
        sae.aliyun.com/app-name: test-yaml    # Application name (static format)
        msePilotAutoEnable: "on"              # Enable microservice governance ("off" to disable)
        mse.lossless.enable: 'true'           # Enable graceful start ("false" to disable)
        mse.lossless.delayTime: '30'          # Delayed registration duration (seconds)
        mse.lossless.warmupTime: '60'         # Traffic warmup duration (seconds)
        mse.lossless.notice: 'true'           # Enable graceful shutdown notification ("false" to disable)
    spec:
      containers:
      - args:
        - /home/admin/start.sh
        command:
        - /bin/bash                          # Valid values: /bin/sh, /bin/bash
        env:
        - name: test
          value: "123"
        - name: my-office
          valueFrom:
            configMapKeyRef:
              key: office
              name: my-config
        image: mock-image                    # Static field for code package deployment
        imagePullPolicy: Always              # Static field
        livenessProbe:
          failureThreshold: 1
          initialDelaySeconds: 1
          periodSeconds: 5
          tcpSocket:
            port: 18081
          timeoutSeconds: 3
        name: main                          # Static field
        readinessProbe:
          failureThreshold: 1
          initialDelaySeconds: 1
          periodSeconds: 5
          successThreshold: 1
          tcpSocket:
            port: 18081
          timeoutSeconds: 5
        resources:
          limits:
            cpu: "2"
            memory: 4Gi
          requests:
            cpu: "2"
            memory: 4Gi
        volumeMounts:
        - mountPath: /tmp/myconfig/name
          name: my-config
          subPath: name
        - mountPath: /tmp/otherconfig
          name: other-config
      hostAliases:
      - hostnames:
        - locahost2
        ip: 127.0.0.2
      - hostnames:
        - localhost
        ip: 127.0.0.1
      restartPolicy: Always                  # Static field
      terminationGracePeriodSeconds: 10
      volumes:
      - configMap:
          name: my-config
        name: my-config
      - configMap:
          name: other-config
        name: other-config

In the directory where application.yaml is located, run:
```
saectl apply -f application.yaml
```

View applications

The saectl tool provides two commands for viewing application information. Use get for a configuration snapshot or list view, and describe for runtime status, events, and health details.

Command	What it returns	When to use
`saectl get deployment`	YAML or JSON configuration snapshot	Export the current configuration as a starting point for edits
`saectl describe deployment`	Runtime status, events, and health details	Troubleshoot a deployment or check live state

List all applications in a namespace

saectl get deployment -n <namespace>

Example output:

NAME          READY   AVAILABLE   TYPE    STATE      LANGUAGE   AGE
my-app        2/2     2           Image   RUNNING    java       3d
test-yaml     0/2     0           Image   PUBLISHING java       10s

The following table describes the output fields.

Field	Description
NAME	Application name
READY	Ready instances / target instances. An instance is ready when its readiness probe passes.
AVAILABLE	Number of currently running instances
TYPE	Deployment method. `Image` indicates image-based deployment.
STATE	Application status: `RUNNING`, `STOPPED`, or `PUBLISHING`
LANGUAGE	Technology stack language
AGE	Time since the application was created

View application configuration

Export the current configuration of a specific application in YAML or JSON format. This is useful as a starting point when editing an existing application's configuration file.

saectl get deployment <deployment-name> -o yaml -n <namespace>

View application details

Get runtime details including events and health status for a specific application.

saectl describe deployment <deployment-name> -n <namespace>

Update applications

The saectl tool provides three commands for updating applications.

Command	What it does	When to use
`scale`	Change the number of running instances	Quick manual scaling
`edit`	Open the configuration in an editor and apply on save	Ad hoc inline edits
`apply`	Apply changes from a local YAML file	Version-controlled configuration updates

Scale an application

saectl scale deployment <deployment-name> -n <namespace> --replicas=<count>

Edit application configuration inline

Open the application configuration in an editor:

saectl edit deployment <deployment-name> -n <namespace>

Modify the configuration in the editor. Save and close the file to apply the changes.

Update application configuration from a file

Modify the local application.yaml file, then run the following command in the directory where the file is located:

saectl apply -f application.yaml

Delete applications

saectl delete deployment <deployment-name> -n <namespace>

K8s YAML configuration reference

SAE applications correspond to the Kubernetes Deployment resource type. The following tables describe the supported configuration fields.

Constraint key:

Label	Meaning
Required (create)	Must be set when creating an application
Create-only	Valid only when creating; not supported when updating
Static	Must use the fixed value shown
Optional	Can be omitted; a default applies if not set
Read-only	Returned in output only; not supported when creating or updating

Metadata fields

Field	Description	Constraint
`metadata.name`	Application name	Required (create); Create-only
`metadata.namespace`	Namespace ID where the application resides	Required (create); Create-only
`metadata.uid`	Application ID	Read-only

Annotation fields (sae.aliyun.com/...)

Annotation	Description	Constraint
`new-sae-version`	SAE application version type (for example, `pro`). See `NewSaeVersion` in CreateApplication.	Required (create); Create-only
`type`	Deployment method: `Image` for image deployment, `FatJar` for JAR packages, `War` for WAR packages. See `PackageType` in CreateApplication.	Required (create); Create-only
`vpc-id`	VPC ID. Required when namespace is not `default`. See `VpcId` in CreateApplication.	Required (create) if namespace is not `default`; Create-only
`vswitch-list`	vSwitch list. Required when namespace is not `default`. See `VSwitchId` in CreateApplication.	Required (create) if namespace is not `default`
`security-group-id`	Security group. If omitted, SAE configures one automatically. See `SecurityGroupId` in CreateApplication.	Optional; Create-only
`language`	Technology stack language. Defaults to `other` if omitted. See `ProgrammingLanguage` in CreateApplication.	Optional
`runtime`	JDK version. See `Jdk` in CreateApplication.	Optional
`package-url`	URL of the uploaded code package. See `PackageUrl` in CreateApplication.	Required for code package deployment
`package-version`	Version number of the deployment package. See `PackageVersion` in CreateApplication.	Optional
`web-container`	Tomcat version for WAR package deployment. See `WebContainer` in CreateApplication.	Optional
`timezone`	Timezone. See `Timezone` in CreateApplication.	Optional
`jar-start-args`	JAR package start command parameters. See `JarStartArgs` in CreateApplication.	Optional
`jar-start-options`	JAR package JVM options. See `JarStartOptions` in CreateApplication.	Optional
`war-start-options`	WAR package JVM options. See `WarStartOptions` in CreateApplication.	Optional
`edas-container-version`	HSF runtime environment version. See `EdasContainerVersion` in CreateApplication.	Optional
`log-sls-config`	Log collection to SLS configuration. See `SlsConfigs` in CreateApplication.	Optional
`log-kafka-config`	Log collection to Kafka configuration. See `KafkaConfigs` in CreateApplication.	Optional
`micro-registration`	Nacos registry selection. See `MicroRegistration` in CreateApplication.	Optional
`micro-registration-config`	Registry configuration. See `MicroRegistrationConfig` in CreateApplication.	Optional
`pvtz-discovery-svc`	K8s Service discovery configuration. See `PvtzDiscoverySvc` in CreateApplication.	Optional
`nas-mount`	NAS mount configuration. See `NasConfigs` in CreateApplication.	Optional
`oss-mount`	OSS mount configuration. See `OssAkId`, `OssAkSecret`, and `OssMountDescs` in CreateApplication.	Optional
`enable-new-arms`	Enable application monitoring. See `EnableNewArms` in CreateApplication.	Optional
`base-app-name`	Baseline application name for end-to-end canary release.	Optional; Create-only
`service-tags`	Grayscale label for end-to-end canary release. See `ServiceTags` in CreateApplication.	Optional
`acr-instance-id`	Container Registry (ACR) Enterprise instance ID. See CreateApplication.	Optional
`custom-image-network-type`	Custom image network type. See `CustomImageNetworkType` in CreateApplication.	Optional
`sidecar-acr-instance-id`	ACR Enterprise instance ID for the sidecar image. See `SidecarContainersConfig` in CreateApplication.	Optional
`enable-sidecar-resource-isolated`	Enable sidecar resource isolation. See `EnableSidecarResourceIsolated` in CreateApplication.	Optional
`state`	Application status.	Read-only

spec fields

Field	Description	Constraint
`spec.replicas`	Number of container instances	Optional
`spec.selector`	Must use the static format below.	Required (create); Create-only; Static
`spec.strategy.type`	Must be `RollingUpdate`	Static; Create-only
`spec.strategy.rollingUpdate.maxSurge`	Must be `0`	Static; Create-only
`spec.strategy.rollingUpdate.maxUnavailable`	Maximum number of unavailable instances during a rolling update. See calculation below.	Optional

Static format for spec.selector:

selector:
  matchLabels:
    sae.aliyun.com/app-name: <application-name>

maxUnavailable is calculated as follows:

If MinReadyInstances is set (not -1): maxUnavailable = Replicas - MinReadyInstances
If MinReadyInstanceRatio is set (not -1): maxUnavailable = Replicas - ceil(Replicas × (MinReadyInstanceRatio / 100))

spec.template fields

Field	Description	Constraint
`spec.template.metadata.labels` (app label)	Must use the static format below.	Required (create); Static

Static format for the app label:

labels:
  sae.aliyun.com/app-name: <application-name>

The following MSE labels enable microservice governance features. Professional Edition applications support these labels by default. Standard Edition applications require allowlisting — contact the DingTalk support group (group ID: 32874633) for details.

labels:
  msePilotAutoEnable: "on"       # Enable microservice governance. "off" to disable.
  mse.lossless.enable: 'true'    # Enable graceful start. "false" to disable.
  mse.lossless.delayTime: '30'   # Delayed registration duration (seconds). If non-zero, configure a business readiness probe.
  mse.lossless.warmupTime: '60'  # Traffic warmup duration (seconds).
  mse.lossless.notice: 'true'    # Enable graceful shutdown notification. "false" to disable.

spec.template.spec.containers[] fields

Field	Description	Constraint
`name`	Must be `main`	Static; Required (create); Create-only
`image`	Container image. For code package deployment, must be `mock-image`.	Required; `mock-image` is Static for code package deployment
`imagePullPolicy`	Must be `Always`	Static; Create-only
`command`	Start command. Valid values: `/bin/sh`, `/bin/bash`	Optional
`args`	Start command parameters (for example, `/home/admin/start.sh`)	Optional
`env`	Container environment variables. Supports direct key-value pairs and ConfigMap references.	Optional
`envFrom`	Reference all key-value pairs from a ConfigMap.	Optional
`resources`	Container instance specifications. Limits and requests must have the same configuration.	Optional
`livenessProbe`	Liveness probe. Fields: `failureThreshold`, `initialDelaySeconds`, `periodSeconds`, `tcpSocket.port`, `timeoutSeconds`.	Optional
`readinessProbe`	Business readiness probe. Same fields as `livenessProbe`, plus `successThreshold`. Required when `mse.lossless.delayTime` is non-zero.	Optional
`volumeMounts`	Mount ConfigMap entries as files. Pair with `volumes`.	Optional

env — direct key-value pair:

env:
  - name: test
    value: "123"

env — ConfigMap reference:

env:
  - name: database
    valueFrom:
      configMapKeyRef:
        key: database             # Key in the ConfigMap
        name: database-configmap  # ConfigMap name

envFrom — full ConfigMap reference:

envFrom:
  - configMapRef:
      name: other-configmap

resources — limits and requests must match:

resources:
  limits:
    cpu: "2"
    memory: 4Gi
  requests:
    cpu: "2"
    memory: 4Gi

volumeMounts and volumes — mount ConfigMap entries as files:

volumeMounts:
  - mountPath: /tmp/config-1
    name: my-config
  - mountPath: /tmp/config-2
    name: other-config

volumes:
  - configMap:
      name: my-config
    name: my-config
  - configMap:
      name: other-config
    name: other-config

Other spec.template.spec fields

Field	Description	Constraint
`spec.template.spec.hostAliases`	Custom host entries (`/etc/hosts` bindings)	Optional
`spec.template.spec.restartPolicy`	Must be `Always`	Static; Create-only
`spec.template.spec.terminationGracePeriodSeconds`	Graceful shutdown timeout in seconds	Optional