Como o APISIX Ingress suporta plugins personalizados

Ingress & Ingress Controller

Ingress é um dos objetos de API do Kubernetes. Ele gerencia o acesso externo aos serviços em um cluster, geralmente HTTP/HTTPS.

Os clientes podem seguir as regras do Ingress para rotear solicitações de clientes para os serviços do cluster Kubernetes ou para um Pod específico.

A seguir está um exemplo de um recurso Ingress:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: apisix-gateway
spec:
  rules:
    - host: apisix.apache.org
      http:
        paths:
          - backend:
              service:
                name: apisix-gateway
                port:
                  number: 80
            path: /
            pathType: Exact

O exemplo acima contém os seguintes conteúdos:

metadata.name: nome do recurso Ingress
spec.rules[].host: domínio usado pelo acesso externo
spec.rules[].http.paths[].backend: descreve informações relacionadas aos serviços em um cluster
spec.rules[].http.paths[].path: descreve os caminhos usados pelo acesso externo aos serviços em um cluster
spec.rules[].http.paths[].pathType: descreve o tipo de caminho para gerenciar o acesso externo aos serviços no cluster

Com base no exemplo acima, podemos notar que a especificação do recurso Ingress é relativamente simples.

Ingress é uma definição de recurso no Kubernetes que não pode lidar com nenhum tráfego por si só. Portanto, se quisermos tornar os recursos Ingress eficazes, devemos usar um controlador para processar esses recursos Ingress, conhecido como Ingress controller.

O Ingress controller ficaria observando quaisquer alterações de recursos no cluster Kubernetes e transformaria as regras de recursos Ingress em regras de proxy da camada de dados para que a camada de dados pudesse lidar com o tráfego.

No ambiente de produção real, há muitos tipos diferentes de solicitações de clientes. Por exemplo, os recursos Ingress não podem descrever diretamente alguns dos recursos mais comuns, como autenticação e reescrita de URI. Então, como podemos atender a esses requisitos?

Como o Ingress-NGINX suporta extensões?

Primeiro, usaremos um exemplo do controlador Ingress-NGINX no ecossistema Kubernetes para demonstrar como usar as extensões.

Podemos usar Annotation para descrever as extensões necessárias dos recursos Ingress no Ingress-NGINX. Por exemplo:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    kubernetes.io/ingress.class: nginx
    nginx.ingress.kubernetes.io/enable-cors: "true"
    nginx.ingress.kubernetes.io/cors-allow-origin: https://foo.com,https://bar.com
    nginx.ingress.kubernetes.io/cors-allow-headers: x-foo-1,x-foo-2
    nginx.ingress.kubernetes.io/cors-allow-methods: GET,POST,PUT
  name: nginx-ingress
spec:
  rules:
    - host: kubernetes.github.io
      http:
        paths:
          - path: /ingress
            pathType: Exact
            backend:
              service:
                name: nginx
                port:
                  number: 80

A configuração acima habilita o CORS.

É relativamente simples adicionar Annotations ao recurso Ingress; no entanto, devemos notar que o controlador Ingress-NGINX precisa suportar totalmente essas Annotations; caso contrário, a configuração não terá efeito. Se precisarmos usar alguns outros recursos não desenvolvidos do controlador Ingress-NGINX, precisamos fazer alguns desenvolvimentos personalizados.

As seções a seguir descrevem como usar o controlador Apache APISIX Ingress para atender a esses requisitos.

Usando plugins no APISIX Ingress

Apache APISIX Ingress utiliza plugins para atender às diversas necessidades dos clientes para lidar com tráfego e cenários específicos. Atualmente, há mais de 80 plugins prontos para uso, e os usuários podem desenvolver plugins personalizados para suportar novos recursos.

Há muitas maneiras diferentes de desenvolver plugins personalizados:

Os usuários podem usar Lua para desenvolver plugins, e esses plugins podem ser executados internamente no APISIX
Os usuários também podem usar outras linguagens de programação para desenvolver plugins; esse mecanismo é chamado de "plugin runner", e os plugins desenvolvidos por esse mecanismo são chamados de "External Plugin"

Consulte a documentação oficial sobre desenvolvimento de plugins:

Desenvolvimento de Plugins: https://apisix.apache.org/docs/apisix/plugin-develop/
Desenvolvimento de Plugins Externos: https://apisix.apache.org/docs/apisix/external-plugin/

Apresentaremos três maneiras de desenvolver plugins usando Lua no APISIX Ingress.

Modo CRD Puro

O controlador APISIX Ingress suporta sua própria especificação CRD, e você pode habilitar diretamente plugins nas regras de roteamento (seja um plugin interno ou um plugin personalizado). Por exemplo:

apiVersion: apisix.apache.org/v2beta3
kind: ApisixRoute
metadata:
  name: httpbin-route
spec:
  http:
    - name: rule1
      match:
        hosts:
          - apisix.apache.org
        paths:
          - /apisix-ingress
      backends:
        - serviceName: apisix-gateway
          servicePort: 80
      plugins:
        - name: cors
          enable: true
          config:
            allow_origins: http://foo.bar.org
            allow_methods: "GET,POST"
            max_age: 3600
            expose_headers: x-foo,x-baz
            allow_headers: x-from-ingress
            allow_credential: true

Os usuários podem usar a configuração acima para criar regras de roteamento, e o plugin cors seria habilitado nessa rota.

Essa é a maneira mais nativa de suporte no APISIX Ingress, e ela se encaixa bem com o APISIX. Além disso, quando os usuários adicionam novos plugins personalizados, o APISIX Ingress não precisa ser redesenvolvido, permitindo que os usuários o usem diretamente.

Modo CRD + Annotations do Ingress

Também podemos usar CRD + Annotations do Ingress para estender os recursos no APISIX Ingress, por exemplo:

apiVersion: apisix.apache.org/v2
kind: ApisixPluginConfig
metadata:
  name: cors-plugin
spec:
  plugins:
    - name: cors
      enable: true
      config:
        allow_origins: http://foo.bar.org
        allow_methods: "GET,POST"
        max_age: 3600
        expose_headers: x-foo,x-baz
        allow_headers: x-from-ingress
        allow_credential: true
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    kubernetes.io/ingress.class: apisix
    k8s.apisix.apache.org/plugin-config-name: cors-plugin
  name: apisix-ingress
spec:
  rules:
    - host: apisix.apache.org
      http:
        paths:
          - path: /apisix-ingress
            pathType: Exact
            backend:
              service:
                name: apisix-gateway
                port:
                  number: 80

Usando a configuração acima, podemos criar independentemente uma configuração de plugin chamada cors-plugin e usar a Annotation k8s.apisix.apache.org/plugin-config-name: cors-plugin do recurso Ingress para referenciá-la. O efeito real é quase o mesmo da primeira configuração; ambos habilitariam o plugin cors para as rotas correspondentes.

Nesse modo, a configuração do plugin pode ser considerada como um recurso independente, e vários recursos Ingress também podem compartilhá-los. Da mesma forma, não há necessidade de fazer nenhum desenvolvimento personalizado.

Modo Annotations do Ingress

Devido à semântica limitada dos recursos Ingress, geralmente usamos annotations para adicionar algumas informações adicionais aos objetos de recurso, que também é a maneira mais comum de estender as capacidades do Ingress. Por exemplo:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    kubernetes.io/ingress.class: apisix
    k8s.apisix.apache.org/enable-cors: "true"
    k8s.apisix.apache.org/cors-allow-origin: https://foo.com,https://bar.com
    k8s.apisix.apache.org/cors-allow-headers: x-foo-1,x-foo-2
    k8s.apisix.apache.org/cors-allow-methods: GET,POST,PUT
  name: apisix-ingress
spec:
  rules:
    - host: apisix.apache.org
      http:
        paths:
          - path: /apisix-ingress
            pathType: Exact
            backend:
              service:
                name: apisix-gateway
                port:
                  number: 80

A configuração acima adicionará algumas informações adicionais relacionadas ao cors ao recurso Ingress. O controlador APISIX Ingress pode então identificar essas informações e transformá-las na configuração da camada de dados para estender os recursos do recurso Ingress.

No entanto, nesse modo, devemos garantir que o controlador APISIX Ingress já seja capaz de processar essas Annotations. Caso contrário, precisamos fazer alguns desenvolvimentos personalizados.

Se você precisar realizar desenvolvimentos personalizados, consulte a seguinte documentação:

Como usar o controlador APISIX Ingress para desenvolver: https://apisix.apache.org/docs/ingress-controller/contribute/

Conclusão

Este artigo introduz principalmente as especificações relacionadas aos recursos Ingress e como estender recursos para recursos Ingress. Por exemplo, no Ingress-NGINX, geralmente só podemos usar Annotations para estender recursos. No entanto, no Apache APISIX Ingress, temos três modos de configuração para atender a requisitos avançados e mais cenários. Além disso, na maioria dos casos, os usuários não precisam de nenhum desenvolvimento personalizado para plugins personalizados.