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

This topic describes how to use the saectl tool and its common commands to help you get started quickly.

Prerequisites

The saectl tool is installed and configured with an AccessKey ID, an AccessKey secret, and an application deployment region. For more information, see Install and configure the saectl tool.

Convert a Kubernetes YAML file to an SAE YAML file

To migrate an application deployed in Kubernetes to SAE, follow these steps:

Run the following command to convert an existing Kubernetes YAML file to an SAE YAML file. An SAE YAML file complies with SAE specifications, which differ from Kubernetes specifications.

saectl convert -f <k8s-compliant-file.yaml> -o <sae-compliant-file.yaml>
# <k8s-compliant-file.yaml>: The name of the existing Kubernetes YAML file.
# <sae-compliant-file.yaml>: The name of the SAE YAML file to be generated.

Run the following command to deploy the application to SAE based on the SAE YAML file.

saectl apply -f <sae-compliant-file.yaml>
# <sae-compliant-file.yaml>: The name of the generated SAE YAML file.

If an error occurs, manually modify the SAE YAML file based on the error message. Then, return to the previous step and run the command again. Errors typically fall into one of the following categories:
1. Some fields supported in Kubernetes YAML files are not supported or have specific format requirements in SAE YAML files. After the conversion, you must manually delete or replace these fields. For more information about the supported fields and format requirements in SAE YAML files, see the other topics in this directory.
2. Some fields that are required for SAE YAML files may be missing from the Kubernetes YAML file. After the conversion, a placeholder in the ${parameter_name} format prompts you to add the field. For example, you only need to manually replace ${vpc-id} with the actual value. In this example, you must associate a VPC when you define a namespace in SAE. Because the original Kubernetes YAML file does not provide the ${vpc-id} parameter, you must add it manually.
```
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, you can define them in the same file. Use the standard Kubernetes separator --- to separate the resources. The saectl tool can convert them to an SAE YAML file in a batch. For example:

apiVersion: apps/v1
kind: Deployment
# ... Deployment Definition ...

---
apiVersion: v1
kind: ConfigMap
# ... ConfigMap Definition ...

However, note that the creation of these resources must not depend on a specific execution order.

For example, if a deployment and a service that depends on the deployment are defined in the same SAE YAML file, an error occurs when the file is run to create both resources at the same time. This is because the service can be created only after the deployment is created.

You must define the deployment and the service in separate SAE YAML files. First, create the deployment. After the deployment is created, create the service.

Example - Deploy Nginx using saectl

The following files define the resources required to deploy Nginx in Kubernetes, including a deployment and a service.

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 the Kubernetes YAML files to SAE YAML files.

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 check its status.

saectl apply -f output-nginx-deployment.yaml
saectl get deployment nginx # Check the deployment status based on the returned result:
# If STATE is PUBLISHING, the deployment is in progress. Wait for a period of time and run this command again to check the status.
# If STATE is RUNNING, the application is deployed. Proceed with the subsequent commands.

Create the service. View the public IP address and port for accessing the service. Then, you can access the service from the public network.

saectl apply -f output-nginx-service.yaml
saectl get service internet-nginx -o wide # Check the service status based on the returned result:
# If EXTERNAL-IP is <pending>, the service is being created. Wait for a period of time and run this command again to check the status.
# If EXTERNAL-IP displays an IP address, the service is created. Use this public IP address and port to access the service.
curl http://<public-ip>:<port> # Verify that the service is deployed. Alternatively, access http://<public-ip>:<port> in a browser.

Clean up resources. Delete the deployment and the service.

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

Convert a docker-compose YAML file to an SAE YAML file

To migrate an application deployed using Docker Compose to SAE, follow these steps:

Manage namespaces

The saectl tool supports creating, viewing, and deleting namespaces. It does not support updating namespaces.

Create a namespace

Create a file named namespace.yaml. The following sample code shows the content of the file, which includes the namespace configuration.

apiVersion: v1
kind: Namespace
metadata:
  annotations:
    sae.aliyun.com/vpc-id: ${vpc-id} # Replace ${vpc-id} with the ID of the VPC to be associated with the namespace. The format is vpc-xxxxxxxxxxxxxxxxxxxxx.
  name: ${namespace} # Replace ${namespace} with the namespace name.
spec: {}

In the directory where the namespace.yaml file is located, run the following command to create the namespace.
```
saectl apply -f namespace.yaml
```

View namespaces

Run the following command to view the existing namespaces in the specified application deployment region.

saectl get ns

The following is an example of the output:

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

The following table describes the fields.

Field	Description
NAME	The name of the namespace. `default` indicates the default namespace.
STATUS	The status of the namespace. `Active` indicates that the namespace is available.
REGION	The region where the namespace is located.

Delete a namespace

Run the following command to delete a specified namespace.

saectl delete ns ${namespace}
# ${namespace} is the name of the namespace.

Manage applications

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

Create an application

Create a file named deployment.yaml. The following sample code shows the content of the file, which includes the application configuration.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: ${deployment-name} # Replace ${deployment-name} with the application name.
spec:
  replicas: 2 # The number of application instances.
  selector:
    matchLabels:
      sae.aliyun.com/app-name: ${deployment-name} # Replace ${deployment-name} with the application name.
  template:
    metadata:
      labels:
        sae.aliyun.com/app-name: ${deployment-name} # Replace ${deployment-name} with the application name.
    spec:
      containers:
      - name: main # Set the container name to main to avoid conflicts.
        image: registry.openanolis.cn/openanolis/nginx:1.14.1-8.6 # This example uses an Nginx image.

In the directory where the deployment.yaml file is located, run the following command to create the application in the default namespace.
```
saectl apply -f deployment.yaml
```
Run the following command to view information about the created application. If the value of the STATE field in the output is RUNNING, the application is running.
```
saectl get deployment ${deployment-name}
# ${deployment-name} is the application name.
```

Run the following command to view the instance information of the created application.

saectl get pods -l sae.aliyun.com/app-name=${deployment-name}
# ${deployment-name} is the application name.

View the application list

Run the following command to view the existing applications in a specified namespace.

saectl get deployment -n ${namespace} 
# ${namespace} is the name of the namespace. If the -n parameter is not used to specify a namespace, the default namespace is used.

The following is an example of the 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

The following table describes the fields.

Field	Description
NAME	The name of the application.
READY	The number of ready application instances / The number of desired target instances. Ready means that the instances have passed the readiness probe check.
AVAILABLE	The number of currently running application instances.
TYPE	The deployment method of the application. `Image` indicates that the application is deployed using an image.
STATE	The status of the application. `Running` indicates that the application is running.
LANGUAGE	The technology stack of the application.
AGE	The age of the application.

View application details

You can use the get or describe command to view application details.

View application configuration using the get command

Run the following command to view the application configuration.

saectl get deployment ${deployment-name} -o yaml -n ${namespace}
# ${deployment-name} is the application name.
# ${namespace} is the name of the namespace. If the -n parameter is not used to specify a namespace, the default namespace is used.

View application details using the describe command

Run the following command to view application details.

saectl describe deployment ${deployment-name} -n ${namespace}
# ${deployment-name} is the application name.
# ${namespace} is the name of the namespace. If the -n parameter is not used to specify a namespace, the default namespace is used.

Update an application

You can use the scale, edit, or apply command to update an application.

Manually scale an application using the scale command

Run the following command to manually scale an application.

saectl scale deployment ${deployment-name} -n ${namespace} --replicas=${pod-num}
# ${deployment-name} is the application name.
# ${namespace} is the name of the namespace. If the -n parameter is not used to specify a namespace, the default namespace is used.
# ${pod-num} is the desired number of application instances.

Edit application configuration online using the edit command

Run the following command. The configuration of the specified application opens in a YAML file.

saectl edit deployment ${deployment-name} -n ${namespace}
# ${deployment-name} is the application name.
# ${namespace} is the name of the namespace. If the -n parameter is not used to specify a namespace, the default namespace is used.

In the opened YAML file, modify the configuration as needed. Then, save and close the file. Wait for the configuration change to be applied.

Update an application based on a YAML configuration file using the apply command

Modify the deployment.yaml configuration file of the deployed application. In the directory where the configuration file is located, run the following command to apply the configuration changes.

saectl apply -f deployment.yaml

Delete an application

Run the following command to delete a specified application.

saectl delete deployment ${deployment-name} -n ${namespace}
# ${deployment-name} is the application name.
# ${namespace} is the name of the namespace. If the -n parameter is not used to specify a namespace, the default namespace is used.

Manage Server Load Balancer (SLB)

Server Load Balancer (SLB) corresponds to the service resource type in Kubernetes. The saectl tool supports creating, viewing, updating, and detaching SLB instances.

Create a new SLB instance for an application

Create a file named svc.yaml. The following sample code shows the content of the file, which includes the SLB configuration.

apiVersion: v1
kind: Service
metadata:
  name: internet-${deployment-name} # Replace ${deployment-name} with the application name.
  # internet specifies a public-facing SLB instance. To specify an internal-facing SLB instance, replace it with intranet.
spec:
  ports:
  - name: port-80
    port: 80 # The port used to access the application. Replace it with the actual port as needed.
    protocol: TCP
    targetPort: 80 # The port exposed by the container. Replace it with the actual port as needed.
  selector:
    sae.aliyun.com/app-name: ${deployment-name} # Replace ${deployment-name} with the application name.

In the directory where the svc.yaml file is located, run the following command to create a new SLB instance for the application.
```
saectl apply -f svc.yaml
```

Attach an application to an existing SLB instance

Create a file named svc.yaml. The following sample code shows the content of the file, which includes the SLB configuration.

apiVersion: v1
kind: Service
metadata:
  annotations:
    sae.aliyun.com/loadbalancer-id: ${your-slb-id} # Replace ${your-slb-id} with the SLB ID.
  name: internet-${deployment-name} # Replace ${deployment-name} with the application name.
  # internet specifies a public-facing SLB instance. To specify an internal-facing SLB instance, replace it with intranet.
spec:
  ports:
  - name: port-80
    port: 80 # The port used to access the application. Replace it with the actual port as needed.
    protocol: TCP
    targetPort: 80 # The port exposed by the container. Replace it with the actual port as needed.
  selector:
    sae.aliyun.com/app-name: ${deployment-name} # Replace ${deployment-name} with the application name.

In the directory where the svc.yaml file is located, run the following command to attach the application to the existing SLB instance.
```
saectl apply -f svc.yaml
```

View the SLB instance list

Run the following command to view the list of existing SLB instances.

saectl get service -l sae.aliyun.com/app-name=${deployment-name} -n ${namespace}
# ${deployment-name} is the application name. If the -l parameter is not used to specify an application name, the SLB instances attached to all applications are displayed by default.
# ${namespace} is the name of the namespace. If the -n parameter is not used to specify a namespace, the default namespace is used.

The following is an example of the 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

The following table describes the fields.

Field	Description
NAME	The name of the service. The format is `${network-type}-${application-name}`. For `${network-type}`, `internet` indicates a public network and `intranet` indicates a private network.
TYPE	The type of the service. `LoadBalancer` indicates an SLB instance.
EXTERNAL-IP	The IP address of the SLB instance.
PORT(S)	The port mapping information of the SLB instance.
BOUND	The name of the application to which the SLB instance is attached.
AGE	The age of the service.

View SLB instance details

Run the following command to view the configuration of an SLB instance.

saectl get service ${service-name} -n ${namespace} -o yaml
# ${service-name} is the service name.
# ${namespace} is the name of the namespace. If the -n parameter is not used to specify a namespace, the default namespace is used.

Update an SLB instance

You can use the edit or apply command to update an SLB instance.

Edit SLB configuration online using the edit command

Run the following command. The configuration of the specified SLB instance opens in a YAML file.

saectl edit service ${service-name} -n ${namespace}
# ${service-name} is the service name.
# ${namespace} is the name of the namespace. If the -n parameter is not used to specify a namespace, the default namespace is used.

In the opened YAML file, modify the configuration as needed. Then, save and close the file. Wait for the configuration change to be applied.

Update an SLB instance based on a YAML configuration file using the apply command

Modify the svc.yaml configuration file of the existing SLB instance. In the directory where the configuration file is located, run the following command to apply the configuration changes.

saectl apply -f svc.yaml

Detach an SLB instance

Run the following command to detach a specified SLB instance.

saectl delete service ${service-name} -n ${namespace}
# ${service-name} is the service name.
# ${namespace} is the name of the namespace. If the -n parameter is not used to specify a namespace, the default namespace is used.

Manage ConfigMaps

The saectl tool supports creating, viewing, updating, and deleting ConfigMaps. A ConfigMap can be referenced as an environment variable in a container or mounted as a file into a container.

Create a ConfigMap

Create a file named cm.yaml. The following sample code shows the content of the file, which includes the ConfigMap configuration.

apiVersion: v1
kind: ConfigMap
metadata:
  name: database-configmap # The name of the ConfigMap.
  namespace: default # The namespace where the ConfigMap is located.
data: # The key-value pairs in the ConfigMap.
  database: mysql
  database_uri: mysql://localhost:2309

In the directory where the cm.yaml file is located, run the following command to create a ConfigMap named database-configmap in the default namespace.
```
saectl apply -f cm.yaml
```

View the ConfigMap list in a region

Run the following command to view the list of existing ConfigMaps in a region.

saectl get configmap -A

The following is an example of the output:

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

The following table describes the fields.

Field	Description
NAMESPACE	The namespace where the ConfigMap is located.
NAME	The name of the ConfigMap.
DATA	The number of data entries in the ConfigMap.
AGE	The age of the ConfigMap.

View the ConfigMap list in a namespace

Run the following command to view the list of existing ConfigMaps in a namespace.

saectl get configmap -n ${namespace}
# ${namespace} is the name of the namespace. If the -n parameter is not used to specify a namespace, the default namespace is used.

View ConfigMap details

Run the following command to view the details of a specified ConfigMap.

saectl get cm ${cm-name} -n ${namespace} -o yaml 
# ${cm-name} is the name of the ConfigMap.
# ${namespace} is the name of the namespace. If the -n parameter is not used to specify a namespace, the default namespace is used.

Reference a ConfigMap as a container environment variable

The following sample file shows how to reference a ConfigMap as a container environment variable. You can reference some or all of the key-value pairs as needed.

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: ### The following is an example of referencing some key-value pairs.
        - name: database # The name of the environment variable in the container.
          valueFrom:
            configMapKeyRef: # The value of the environment variable references the value of the database key in database-configmap.
              key: database
              name: database-configmap
        envFrom: ### The following is an example of referencing all key-value pairs.
        - configMapRef: # All key-value pairs in other-configmap are referenced as environment variables in the container.
            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 a ConfigMap as a file into a container

The following sample file shows how to mount a ConfigMap as a file into a 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 # The mount path of the ConfigMap file.
            name: my-volume # The name of the mounted volume is my-volume.
      volumes: # Declare my-volume based on nacos-configmap.
      - configMap:
          name: nacos-configmap
        name: my-volume
      restartPolicy: Always
      terminationGracePeriodSeconds: 10

Update a ConfigMap

You can use the edit or apply command to update a ConfigMap.

Edit a ConfigMap online using the edit command

Run the following command. The configuration of the specified ConfigMap opens in a YAML file.

saectl edit cm ${cm-name} -n ${namespace}
# ${cm-name} is the name of the ConfigMap.
# ${namespace} is the name of the namespace. If the -n parameter is not used to specify a namespace, the default namespace is used.

In the opened YAML file, modify the configuration as needed. Then, save and close the file. Wait for the configuration change to be applied.

Update a ConfigMap based on a YAML configuration file using the apply command

Modify the cm.yaml configuration file of the existing ConfigMap. In the directory where the configuration file is located, run the following command to apply the configuration changes.

saectl apply -f cm.yaml

Delete a ConfigMap

Run the following command to delete a specified ConfigMap.

saectl delete cm ${cm-name} -n ${namespace}
# ${cm-name} is the name of the ConfigMap.
# ${namespace} is the name of the namespace. If the -n parameter is not used to specify a namespace, the default namespace is used.