Quick start for the saectl tool - Serverless App Engine - Centro de documentación de Alibaba Cloud

saectl es la herramienta de línea de comandos para Serverless App Engine (SAE). Úsela para convertir archivos YAML de Kubernetes y Docker Compose al formato de SAE, y gestione el ciclo de vida completo de sus recursos de SAE: namespaces, aplicaciones, instancias de Server Load Balancer (SLB) y ConfigMaps.

Requisitos previos

Antes de empezar, asegúrese de contar con lo siguiente:

saectl instalado y configurado con un AccessKey ID, un AccessKey secret y una región de despliegue de aplicaciones; consulte Install and configure the saectl tool

Inicio rápido

Los siguientes comandos muestran el flujo de trabajo mínimo para convertir un archivo YAML de Kubernetes y desplegar una aplicación en 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

Para consultar un ejemplo integral de extremo a extremo, véase Desplegar Nginx con saectl.

Conversión de un archivo YAML de Kubernetes a un archivo YAML de SAE

Los archivos YAML de SAE siguen las especificaciones de SAE, las cuales difieren de las de Kubernetes. Utilice el comando convert para generar un archivo compatible con SAE a partir de un archivo YAML de Kubernetes existente y, posteriormente, despliéguelo con apply.

Convierta el archivo YAML de Kubernetes:

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

Despliegue la aplicación:

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

Si ocurre un error, corrija el archivo YAML de SAE según el mensaje de error y ejecute apply nuevamente. Los errores se clasifican en dos categorías:
- Campos no compatibles o con formato diferente: Algunos campos en los archivos YAML de Kubernetes no son compatibles o tienen requisitos de formato distintos en los archivos YAML de SAE. Elimine o reemplace estos campos después de la conversión. Para conocer los campos compatibles y sus requisitos de formato, consulte los demás temas de este directorio.
- Campos obligatorios faltantes: Es posible que algunos campos requeridos por los archivos YAML de SAE no estén presentes en el archivo YAML de Kubernetes. Tras la conversión, un marcador de posición ${parameter_name} indica cada campo faltante. Reemplace el marcador de posición con el valor correspondiente. Por ejemplo, SAE requiere una Virtual Private Cloud (VPC) al definir un namespace, pero los archivos YAML de Kubernetes no incluyen este parámetro. Después de la conversión, el marcador de posición ${vpc-id} aparece en la salida:
```
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: {}
```

Importante

Si un archivo YAML de Kubernetes define varios recursos, sepárelos con el separador estándar de Kubernetes --- dentro de un solo archivo. saectl convierte todos los recursos en un solo lote. No obstante, los recursos en el mismo archivo no deben depender de un orden de ejecución específico. Por ejemplo, si un Deployment y un Service que depende de dicho Deployment están en el mismo archivo, el despliegue fallará porque ambos recursos se crean simultáneamente. Defina los recursos que dependen del orden en archivos separados y aplíquelos en secuencia.

Desplegar Nginx con saectl

Este ejemplo despliega Nginx en SAE mediante dos archivos YAML de Kubernetes (un Deployment y un Service) y, posteriormente, limpia los recursos.

Comience con los siguientes dos archivos YAML de Kubernetes: 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

Convierta ambos archivos al formato YAML de SAE:

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

Despliegue el Deployment y compruebe su estado:

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

Espere hasta que STATE sea RUNNING antes de continuar.

Cree el Service y obtenga la dirección IP pública:

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

Una vez que EXTERNAL-IP muestre una dirección IP, acceda a la aplicación:

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

Limpieza: elimine el Deployment y el Service cuando haya terminado:

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

Conversión de un archivo de Docker Compose a un archivo YAML de SAE

Para migrar una aplicación de Docker Compose a SAE:

Convierta el archivo YAML de Docker Compose a un archivo YAML de Kubernetes. Para obtener instrucciones, consulte la documentación de Kompose.
Convierta el archivo YAML de Kubernetes a un archivo YAML de SAE mediante saectl convert, como se describió anteriormente.

Gestión de namespaces

saectl permite crear, consultar y eliminar namespaces. No se admite la actualización de namespaces.

Crear un namespace

Cree un archivo llamado namespace.yaml con el siguiente contenido:

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

Aplique el archivo para crear el namespace:
```
saectl apply -f namespace.yaml
```

Consultar namespaces

saectl get ns

Salida de ejemplo:

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

Campo	Descripción
NAME	Nombre del namespace. `default` es el namespace predeterminado.
STATUS	Estado del namespace. `Active` indica que el namespace está disponible.
REGION	Región donde se encuentra el namespace.

Eliminar un namespace

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

Gestión de aplicaciones

saectl permite crear, consultar, actualizar y eliminar aplicaciones.

Crear una aplicación

Cree un archivo llamado deployment.yaml con el siguiente contenido:

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

Aplique el archivo para crear la aplicación en el namespace predeterminado:
```
saectl apply -f deployment.yaml
```

Compruebe que la aplicación se esté ejecutando:

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

Consulte las instancias de Pod de la aplicación:

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

Consultar la lista de aplicaciones

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

Salida de ejemplo:

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

Campo	Descripción
NAME	Nombre de la aplicación.
READY	Instancias listas frente a instancias objetivo. Una instancia se considera lista cuando supera la comprobación de sonda de disponibilidad.
AVAILABLE	Instancias en ejecución actualmente.
TYPE	Método de despliegue. `Image` indica que la aplicación se despliega desde una imagen de contenedor.
STATE	Estado de la aplicación. `RUNNING` significa que la aplicación se está ejecutando.
LANGUAGE	Pila tecnológica de la aplicación.
AGE	Tiempo transcurrido desde que la aplicación está en ejecución.

Consultar detalles de la aplicación

Utilice get para ver la configuración YAML o describe para ver todos los detalles.

Consultar la configuración de la aplicación

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

Consultar detalles de la aplicación

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

Actualizar una aplicación

Hay tres comandos disponibles: scale, edit y apply.

Escalar una aplicación

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

Editar la configuración de la aplicación en línea

Abra la configuración YAML de la aplicación en un editor:

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

Modifique la configuración, guarde y cierre el archivo. Los cambios se aplican automáticamente.

Aplicar configuración actualizada desde un archivo

Modifique deployment.yaml y ejecute:

saectl apply -f deployment.yaml

Eliminar una aplicación

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

Gestión de instancias de SLB

Las instancias de SLB corresponden al tipo de recurso Service en Kubernetes. saectl permite crear, consultar, actualizar y desvincular instancias de SLB.

Crear una nueva instancia de SLB

Cree un archivo llamado svc.yaml con el siguiente contenido:

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}

Aplique el archivo para crear la instancia de SLB:
```
saectl apply -f svc.yaml
```

Vincular una aplicación a una instancia de SLB existente

Cree un archivo llamado svc.yaml con la anotación sae.aliyun.com/loadbalancer-id:

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}

Aplique el archivo:
```
saectl apply -f svc.yaml
```

Consultar instancias de SLB

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

Salida de ejemplo:

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

Campo	Descripción
NAME	Nombre del servicio con el formato `<network-type>-<application-name>`. `internet` = red pública, `intranet` = red privada.
TYPE	Tipo de servicio. `LoadBalancer` indica una instancia de SLB.
EXTERNAL-IP	Dirección IP de la instancia de SLB.
PORT(S)	Asignación de puertos de la instancia de SLB.
BOUND	Aplicación a la que está vinculada la instancia de SLB.
AGE	Tiempo transcurrido desde la creación del servicio.

Consultar detalles de una instancia de SLB

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

Actualizar una instancia de SLB

Utilice edit para actualizar en línea o apply para actualizar desde un archivo.

Editar la configuración de SLB en línea

Abra la configuración de SLB en un editor:

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

Modifique la configuración, guarde y cierre el archivo. Los cambios se aplican automáticamente.

Aplicar configuración actualizada desde un archivo

Modifique svc.yaml y ejecute:

saectl apply -f svc.yaml

Desvincular una instancia de SLB

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

Gestión de ConfigMaps

saectl permite crear, consultar, actualizar y eliminar ConfigMaps. Un ConfigMap almacena configuración como pares clave-valor, los cuales puede referenciar como variables de entorno o montar como archivo dentro de un contenedor.

Crear un ConfigMap

Cree un archivo llamado cm.yaml con el siguiente contenido:

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

Aplique el archivo para crear el ConfigMap:
```
saectl apply -f cm.yaml
```

Consultar ConfigMaps

Listar ConfigMaps en todos los namespaces

saectl get configmap -A

Salida de ejemplo:

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

Campo	Descripción
NAMESPACE	Namespace donde se encuentra el ConfigMap.
NAME	Nombre del ConfigMap.
DATA	Número de pares clave-valor en el ConfigMap.
AGE	Tiempo transcurrido desde la creación del ConfigMap.

Listar ConfigMaps en un namespace

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

Consultar detalles de un ConfigMap

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

Usar un ConfigMap en un contenedor

Referenciar como variables de entorno

Monte pares clave-valor individuales o todos los pares como variables de entorno:

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

Montar como archivo

Monte un ConfigMap como archivo en una ruta específica dentro del contenedor:

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

Actualizar un ConfigMap

Utilice edit para actualizar en línea o apply para actualizar desde un archivo.

Editar un ConfigMap en línea

Abra el ConfigMap en un editor:

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

Modifique la configuración, guarde y cierre el archivo. Los cambios se aplican automáticamente.

Aplicar configuración actualizada desde un archivo

Modifique cm.yaml y ejecute:

saectl apply -f cm.yaml

Eliminar un ConfigMap

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

Pasos siguientes

Install and configure the saectl tool
Explore los demás temas de este directorio para conocer los campos YAML compatibles y los requisitos de formato para los archivos YAML de SAE.