Quick start for the saectl tool - Serverless App Engine: Central de Documentação do Alibaba Cloud

Pré-requisitos

Antes de começar, certifique-se de ter:

O saectl instalado e configurado com um AccessKey ID, um AccessKey secret e uma região de implantação da aplicação — consulte Instalar e configurar a ferramenta saectl

Início rápido

Os comandos a seguir demonstram o fluxo de trabalho mínimo para converter um arquivo YAML do Kubernetes e implantar uma aplicação no 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 um exemplo completo de ponta a ponta, consulte Implantar o Nginx usando o saectl.

Converter um arquivo YAML do Kubernetes para um arquivo YAML do SAE

Os arquivos YAML do SAE seguem especificações próprias, diferentes das especificações do Kubernetes. Use o comando convert para gerar um arquivo compatível com o SAE a partir de um arquivo YAML do Kubernetes existente e, em seguida, implante-o com apply.

Converta o arquivo YAML do Kubernetes:

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

Implante a aplicação:

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

Caso ocorra um erro, corrija o arquivo YAML do SAE com base na mensagem de erro e execute apply novamente. Os erros se dividem em duas categorias:
- Campos não suportados ou com formatação diferente: Alguns campos presentes em arquivos YAML do Kubernetes não são suportados ou possuem requisitos de formato distintos nos arquivos YAML do SAE. Exclua ou substitua esses campos após a conversão. Para consultar os campos suportados e seus requisitos de formato, veja os outros tópicos deste diretório.
- Campos obrigatórios ausentes: Certos campos exigidos pelos arquivos YAML do SAE podem estar ausentes no arquivo YAML do Kubernetes. Após a conversão, um placeholder ${parameter_name} marca cada campo faltante. Substitua o placeholder pelo valor real. Por exemplo, o SAE exige uma Virtual Private Cloud (VPC) ao definir um namespace, mas os arquivos YAML do Kubernetes não incluem esse parâmetro. Depois da conversão, o placeholder ${vpc-id} aparece na saída:
```
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

Se um arquivo YAML do Kubernetes definir múltiplos recursos, separe-os com o separador padrão do Kubernetes --- em um único arquivo. O saectl converte todos os recursos em um único lote. No entanto, os recursos no mesmo arquivo não devem depender de uma ordem específica de execução. Por exemplo, se um Deployment e um Service que depende desse Deployment estiverem no mesmo arquivo, a implantação falhará porque ambos os recursos serão criados simultaneamente. Defina recursos com dependência de ordem em arquivos separados e aplique-os em sequência.

Implantar o Nginx usando o saectl

Este exemplo implanta o Nginx no SAE usando dois arquivos YAML do Kubernetes — um Deployment e um Service — e depois realiza a limpeza dos recursos.

Comece com os dois arquivos YAML do Kubernetes a seguir: 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

Converta ambos os arquivos para o formato YAML do SAE:

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

Implante o Deployment e verifique seu status:

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

Aguarde até que o STATE seja RUNNING antes de continuar.

Crie o Service e obtenha o endereço IP público:

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

Assim que o EXTERNAL-IP exibir um endereço IP, acesse a aplicação:

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

Limpeza — exclua o Deployment e o Service ao terminar:

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

Converter um arquivo do Docker Compose para um arquivo YAML do SAE

Para migrar uma aplicação do Docker Compose para o SAE:

Converta o arquivo YAML do Docker Compose para um arquivo YAML do Kubernetes. Para obter instruções, consulte a documentação do Kompose.
Converta o arquivo YAML do Kubernetes para um arquivo YAML do SAE usando saectl convert, conforme descrito acima.

Exemplo - Implantar o Dify usando o saectl

Gerencie namespaces

O saectl permite criar, visualizar e excluir namespaces. A atualização de namespaces não é suportada.

Crie um namespace

Crie um arquivo chamado namespace.yaml com o seguinte conteúdo:

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 o arquivo para criar o namespace:
```
saectl apply -f namespace.yaml
```

Visualize namespaces

saectl get ns

Exemplo de saída:

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

Campo	Descrição
NAME	Nome do namespace. `default` é o namespace padrão.
STATUS	Status do namespace. `Active` indica que o namespace está disponível.
REGION	Região onde o namespace está localizado.

Exclua um namespace

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

Gerencie aplicações

O saectl suporta a criação, visualização, atualização e exclusão de aplicações.

Crie uma aplicação

Crie um arquivo chamado deployment.yaml com o seguinte conteúdo:

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 o arquivo para criar a aplicação no namespace padrão:
```
saectl apply -f deployment.yaml
```

Verifique se a aplicação está em execução:

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

Visualize as instâncias de Pod da aplicação:

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

Visualize a lista de aplicações

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

Exemplo de saída:

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	Descrição
NAME	Nome da aplicação.
READY	Instâncias prontas / instâncias alvo. Uma instância é considerada pronta quando passa na verificação do probe de readiness.
AVAILABLE	Instâncias atualmente em execução.
TYPE	Método de implantação. `Image` indica que a aplicação foi implantada a partir de uma imagem de contêiner.
STATE	Status da aplicação. `RUNNING` significa que a aplicação está em execução.
LANGUAGE	Stack tecnológica da aplicação.
AGE	Tempo de execução da aplicação.

Visualize detalhes da aplicação

Use get para visualizar a configuração YAML ou describe para ver todos os detalhes.

Visualize configuração da aplicação

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

Visualize detalhes da aplicação

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

Atualize uma aplicação

Três comandos estão disponíveis: scale, edit e apply.

Dimensionar uma aplicação

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

Edite configuração da aplicação online

Abra a configuração YAML da aplicação em um editor:

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

Modifique a configuração, salve e feche o arquivo. As alterações são aplicadas automaticamente.

Aplicar configuração atualizada a partir de um arquivo

Modifique o arquivo deployment.yaml e execute:

saectl apply -f deployment.yaml

Exclua uma aplicação

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

Gerencie instâncias de SLB

As instâncias de SLB correspondem ao tipo de recurso Service no Kubernetes. O saectl permite criar, visualizar, atualizar e desanexar instâncias de SLB.

Crie uma nova instância de SLB

Crie um arquivo chamado svc.yaml com o seguinte conteúdo:

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 o arquivo para criar a instância de SLB:
```
saectl apply -f svc.yaml
```

Anexar uma aplicação a uma instância de SLB existente

Crie um arquivo chamado svc.yaml com a anotação 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 o arquivo:
```
saectl apply -f svc.yaml
```

Visualize instâncias 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

Exemplo de saída:

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	Descrição
NAME	Nome do serviço no formato `<network-type>-<application-name>`. `internet` = rede pública, `intranet` = rede privada.
TYPE	Tipo de serviço. `LoadBalancer` indica uma instância de SLB.
EXTERNAL-IP	Endereço IP da instância de SLB.
PORT(S)	Mapeamento de portas da instância de SLB.
BOUND	Aplicação à qual a instância de SLB está anexada.
AGE	Tempo de existência do serviço.

Visualize detalhes da instância de SLB

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

Atualize uma instância de SLB

Use edit para atualizar online ou apply para atualizar a partir de um arquivo.

Edite configuração do SLB online

Abra a configuração do SLB em um editor:

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

Modifique a configuração, salve e feche o arquivo. As alterações são aplicadas automaticamente.

Aplicar configuração atualizada a partir de um arquivo

Modifique o arquivo svc.yaml e execute:

saectl apply -f svc.yaml

Desanexar uma instância de SLB

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

Gerencie ConfigMaps

O saectl suporta a criação, visualização, atualização e exclusão de ConfigMaps. Um ConfigMap armazena configurações como pares chave-valor, que podem ser referenciados como variáveis de ambiente ou montados como um arquivo dentro de um contêiner.

Crie um ConfigMap

Crie um arquivo chamado cm.yaml com o seguinte conteúdo:

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 o arquivo para criar o ConfigMap:
```
saectl apply -f cm.yaml
```

Visualize ConfigMaps

Listar ConfigMaps em todos os namespaces

saectl get configmap -A

Exemplo de saída:

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

Campo	Descrição
NAMESPACE	Namespace onde o ConfigMap está localizado.
NAME	Nome do ConfigMap.
DATA	Quantidade de pares chave-valor no ConfigMap.
AGE	Tempo de existência do ConfigMap.

Listar ConfigMaps em um namespace

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

Visualize detalhes do ConfigMap

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

Usar um ConfigMap em um contêiner

Referenciar como variáveis de ambiente

Monte pares chave-valor individuais ou todos os pares como variáveis de ambiente:

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 um arquivo

Monte um ConfigMap como um arquivo em um caminho especificado dentro do contêiner:

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

Atualize um ConfigMap

Use edit para atualizar online ou apply para atualizar a partir de um arquivo.

Edite um ConfigMap online

Abra o ConfigMap em um editor:

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

Modifique a configuração, salve e feche o arquivo. As alterações são aplicadas automaticamente.

Aplicar configuração atualizada a partir de um arquivo

Modifique o arquivo cm.yaml e execute:

saectl apply -f cm.yaml

Exclua um ConfigMap

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

Próximos passos

Instale e configure a ferramenta saectl
Explore os outros tópicos deste diretório para conhecer os campos YAML suportados e os requisitos de formato para arquivos YAML do SAE.