Tarefas de integração do Kubernetes

Você está vendo a documentação do Apigee Edge.
Acesse a documentação da Apigee X.
informações

Como adicionar um plug-in personalizado

É possível adicionar novos recursos ao microgateway escrevendo plug-ins personalizados. Com os plug-ins personalizados, é possível interagir de maneira programática com as solicitações e as respostas que fluem pelo microgateway.

Nesta seção, explicamos como empacotar e implantar plug-ins em uma instância do Edge Microgateway em execução no cluster do Kubernetes.

O restante desta seção pressupõe que você esteja familiarizado com a criação e a configuração de plug-ins para uma configuração padrão do Edge Microgateway. Caso contrário, consulte Desenvolver plug-ins personalizados.

Empacotar seus plug-ins

Para empacotar plug-ins personalizados, siga estas etapas:

  1. Crie e teste o plug-in de acordo com as instruções em Criar um plug-in simples.

  2. Coloque o código do plug-in na estrutura de diretórios adequada. Os diretórios do plug-in precisam seguir uma estrutura definida. O exemplo a seguir mostra a estrutura que você precisa seguir, em que response-uppercase e request-headers são os nomes das pastas que contêm o código do plug-in personalizado. Esses nomes são apenas exemplos. Os nomes das pastas podem ser diferentes:

    plugin
      |
      |-- plugins
        |
        |- response-uppercase
        |     |- index.js
        |     |- package.json
        |- request-headers
        |     | - index.js
              | - package.json
    
  3. cd para a pasta plugin.

  4. Na pasta plugin, compacte toda a pasta plugins:

    zip -r plugins.zip plugins/

Criar uma imagem do Docker

  1. No mesmo diretório em que o arquivo ZIP está localizado, crie um novo arquivo chamado Dockerfile.
  2. Adicione o código abaixo a Dockerfile e salve o arquivo:

    FROM gcr.io/apigee-microgateway/edgemicro:latest
    RUN apt-get install unzip
    COPY plugins.zip /opt/apigee/
    RUN chown apigee:apigee /opt/apigee/plugins.zip
    RUN su - apigee -c "unzip /opt/apigee/plugins.zip -d /opt/apigee"
    EXPOSE 8000
    EXPOSE 8443
    ENTRYPOINT ["entrypoint"]
    
  3. Crie uma nova imagem Docker do Edge Microgateway com seus plug-ins e a envie para o registro do Docker. Use o registro que quiser, como docker.io ou gcr.io:

    docker build -t edgemicroplugins .
    docker tag edgemicroplugins container-registry/your-project/edgemicroplugins
    docker push container-registry/your-project/edgemicroplugins
    

    Exemplo:

    docker build -t edgemicroplugins .
    docker tag edgemicroplugins gcr.io/my-project/edgemicroplugins
    docker push   gcr.io/my-project/edgemicroplugins
    

Atualizar a configuração do Edge Microgateway

  1. Adicione os plug-ins ao seu arquivo de configuração do Edge Microgateway. O arquivo de configuração pode ser encontrado aqui:

    $HOME/.edgemicro/org-env-config.yaml
    

    Exemplo:

    $HOME/.edgemicro/myorg-test-config.yaml

No exemplo de configuração a seguir, o plug-in personalizado response-uppercase foi adicionado. O plug-in oauth já estava lá por padrão.

  edgemicro:
    ...
    plugins:
      sequence:
        - oauth
        - response-uppercase

Atualizar o cluster do Kubernetes

A etapa final é aplicar a alteração de configuração ao cluster do Kubernetes. O Kubernetes extrairá a nova imagem com o código do plug-in enviado para o Container Registry e a usará para qualquer pod recém-criado.

Se você implantou o Edge Microgateway como serviço

Use o comando edgemicroctl para injetar a configuração atualizada do Edge Microgateway:

  1. Atualize a implantação do Edge Microgateway com a nova imagem. Exemplo:

    kubectl apply -f <(edgemicroctl -org=your_organization -env=your_environment -key=configuration_key -sec=configuration_secret -conf=config_file_path -img=container-registry/your_project_name/image_name:latest)

    onde:

    • your_organization: a organização da Apigee que você especificou no comando edgemicro configure.
    • your_environment: o ambiente especificado no comando edgemicro configure.
    • configuration_key: a chave retornada do comando edgemicro configure.
    • configuration_secret: o secret retornado do comando edgemicro configure.
    • config_file_path: o caminho para o arquivo de configuração do Edge Micro retornado do comando edgemicro configure.
    • container-registry: o registro do Docker para onde você enviou a imagem. Por exemplo, gcr.io ou docker.io.
    • your_project_name: o nome do projeto do repositório do Docker para onde você enviou a imagem do Docker.
    • image_name: o nome da imagem do Docker que você enviou.

    Exemplo:

    kubectl apply -f <(edgemicroctl -org=jdoe -env=test -key=f2d2eaa52b758493d00cec656e574ac947bee1d701c5c5f3295e5eaa39a3b -sec=0c38cda3fac6c59152f15657052ba1728f8003c1a763cf08da2a -conf=/Users/jdoe/.edgemicro/apigeesearch-test-config.yaml -img=gcr.io/jdoe-project/edgemicroplugins:latest)
  2. Testar o plug-in. Chame a API para ver se você consegue o comportamento esperado. Por exemplo, para o plug-in de "resposta em maiúsculas", o texto da resposta é convertido para todas as letras maiúsculas, conforme mostrado abaixo:

    curl $GATEWAY_IP -H 'x-api-key:3eqeedJRFLlCshwWBiXq4xKFoH1Se3xR'

    Saída:

    HELLO WORLD
    
Como injetar manualmente a nova configuração

A injeção manual é uma abordagem direta, em que você injeta a nova configuração pela linha de comando.

  1. execute o seguinte comando:

    kubectl apply -f <(edgemicroctl -org=your_org -env=your_env -key=your_key -sec=your_secret -conf=config_file_path -img=container-registry/your_project_name/image_name:latest -svc=service_deployment_file)

    onde:

    • your_org: a organização da Apigee que você especificou no comando edgemicro configure.
    • your_env: o ambiente especificado no comando edgemicro configure.
    • your_key: a chave retornada do comando edgemicro configure.
    • your_secret: o secret retornado do comando edgemicro configure.
    • config_file_path: o caminho para o arquivo de configuração do Edge Micro retornado do comando edgemicro configure.
    • container-registry: o registro do Docker para onde você enviou a imagem. Por exemplo, gcr.io ou docker.io.
    • your_project_name: o nome do projeto do repositório do Docker para onde você enviou a imagem do Docker.
    • image_name: o nome da imagem do Docker que você enviou.
    • service_deployment_file: o caminho para o arquivo de implantação do serviço ao qual os plug-ins serão aplicados. Por exemplo, samples/helloworld/helloworld.yaml.

    Exemplo:

    kubectl apply -f <(edgemicroctl -org=myorg -env=test-key=0e3ecea28a64099410594406b30e54439af5265f8 -sec=e3919250bee37c69cb2e5b41170b488e1c1d -conf=/Users/jdoe/.edgemicro/myorg-test-config.yaml -img=gcr.io/myproject/edgemicroplugins:latest -svc=samples/helloworld/helloworld.yaml)
  2. Testar o plug-in. Chame a API do serviço para ver se você consegue o comportamento esperado. Por exemplo, no plug-in "response em maiúsculas", o texto da resposta é convertido em todas as letras maiúsculas, conforme mostrado abaixo:

    curl $GATEWAY_IP -H 'x-api-key:3eqeedJRFLlCshwWBiXq4xKFoH1Se3xR'

    Saída:

    HELLO WORLD
    

Como fazer alterações na configuração do Edge Microgateway

Em alguns casos, pode ser necessário modificar sua configuração do Edge Microgateway. Por exemplo, talvez você queira adicionar um novo plug-in ao Edge Microgateway ou alterar um parâmetro de configuração. Nesta seção, explicamos como fazer e aplicar alterações de configuração ao Edge Microgateway em execução no Kubernetes.

  1. Crie um arquivo de configuração secret.yaml, conforme mostrado abaixo:

    apiVersion: v1
    kind: Secret
    metadata:
      name: mgwsecret
    type: Opaque
    data:
      mgorg: EDGEMICRO_ORG
      mgenv: EDGEMICRO_ENV
      mgkey: EDGEMICRO_KEY
      mgsecret: EDGEMICRO_SECRET
      mgconfig: EDGEMICRO_CONFIG
    
  2. Especifique o valor codificado em base64 de EDGEMICRO_ORG, EDGEMICRO_ENV, EDGEMICRO_KEY, EDGEMICRO_SECRET:

    echo -n "your-org" | base64 | tr -d '\n'
    echo -n "your-org-env" | base64 | tr -d '\n'
    echo -n "your-mg-key" | base64 | tr -d '\n'
    echo -n "your-mg-secret" | base64 | tr -d '\n'
    
  3. Faça as alterações no arquivo de configuração do Edge Microgateway para sua organização e seu ambiente:

    $HOME/.edgemicro/your_org-your_env-config.yaml
  4. Codifique em Base64 o dobro do conteúdo do arquivo de configuração:

    cat $HOME/.edgemicro/org-env-config.yaml | base64 | tr -d '\n' | base64  | tr -d '\n'
  5. Aplique alterações ao Kubernetes no namespace em que o serviço está sendo executado.

    kubectl apply -f secret.yaml -n 

Essas novas alterações não são detectadas automaticamente pelos pods de microgateway atuais. No entanto, os novos pods receberão as alterações. É possível excluir o pod existente para que a implantação crie um novo pod que capture a alteração.

Exemplo de serviço

O exemplo a seguir mostra como atualizar uma implantação de serviço com um novo

  1. Receba os pods.

    kubectl get pods

    Exemplo de saída:

    NAME                                 READY     STATUS    RESTARTS   AGE
    edge-microgateway-57ccc7776b-g7nrg   1/1       Running   0          19h
    helloworld-6987878fc4-cltc2          1/1       Running   0          1d
    
  2. Exclua o pod edge-microgateway.

    kubectl delete pod edge-microgateway-57ccc7776b-g7nrg

    Exemplo de saída:

    pod "edge-microgateway-57ccc7776b-g7nrg" deleted
    
  3. Receba os pods novamente. Um novo pod é ativado e recebe as alterações de configuração.

    kubectl get pods

    Exemplo de saída:

    NAME                                 READY     STATUS    RESTARTS   AGE
    edge-microgateway-57ccc7776b-7f6tc   1/1       Running   0          5s
    helloworld-6987878fc4-cltc2          1/1       Running   0          1d
    

Como escalonar sua implantação

Esta seção explica como usar os princípios de escalonamento do Kubernetes para escalonar as implantações.

Como escalonar uma implantação de serviço

  1. Verifique as implantações:

    kubectl get deployments

    Exemplo de saída:

    NAME                DESIRED   CURRENT   UP-TO-DATE   AVAILABLE   AGE
    edge-microgateway   1         1         1            1           18h
    helloworld          1         1         1            1           1d
    

    A saída indica que uma réplica foi implantada.

  2. Escalone a implantação de uma para quantas réplicas quiser. Neste exemplo, o serviço edge-microgateway é escalonado.

    kubectl scale deployment edge-microgateway --replicas=2
  3. (Opcional) Se quiser usar o escalonamento automático, use este comando:

    kubectl autoscale deployment edge-microgateway --cpu-percent=50 --min=1 --max=10
  4. Verifique as implantações para confirmar que o escalonamento está ativado:

    kubectl get deployments

    Exemplo de saída:

    NAME                DESIRED   CURRENT   UP-TO-DATE   AVAILABLE   AGE
    edge-microgateway   2         2         2            2           18h
    helloworld          1         1         1            1           1d
    

    O estado foi alterado para incluir duas réplicas.

  5. Verifique os pods:

    kubectl get pods

    Exemplo de saída:

    NAME                                 READY     STATUS    RESTARTS   AGE
    edge-microgateway-57ccc7776b-g7nrg   1/1       Running   0          18h
    edge-microgateway-57ccc7776b-rvfz4   1/1       Running   0          41s
    helloworld-6987878fc4-cltc2          1/1       Running   0          1d
    

    A saída mostra que as duas réplicas estão em estado de execução.

Usar namespaces para várias configurações do Edge Microgateway

É possível implantar e configurar várias instâncias de serviços do Edge Microgateway no seu cluster do Kubernetes. Esse caso de uso permite configurar cada instância de microgateway com o próprio conjunto de plug-ins e parâmetros. Exemplo:

  • O serviço A do Edge Microgateway requer apenas o plug-in de detenção de pico.
  • O serviço B do Edge Microgateway requer cota e plug-in do OAuth, mas não a prisão de pico.

Para resolver esse caso de uso, use os namespaces do Kubernetes. Por exemplo, é possível implantar o serviço A do Edge Microgateway no namespace foo e o serviço B do Edge Microgateway no namespace bar.

No exemplo a seguir, o Edge Microgateway configurado na organização OrgA é implantado como um serviço no namespace foo usando a opção -n:

kubectl apply -f <(edgemicroctl -org=myorgA -env=test-key=0e3ecea28a64099410594406b30e54439af5265f8 -sec=e3919250bee37c69cb2e5b41170b488e1c1d -conf=/Users/joed/.edgemicro/orgA-test-config.yaml -svc=samples/helloworld/helloworld.yaml) -n foo

Da mesma forma, no exemplo a seguir, o Edge Microgateway configurado na organização OrgB é implantado como um serviço no namespace bar usando a opção -n:

kubectl apply -f <(edgemicroctl -org=myorgB -env=test-key=0e3ecea28a64099410594406b30e54439af5265f8 -sec=e3919250bee37c69cb2e5b41170b488e1c1d -conf=/Users/joed/.edgemicro/orgB-test-config.yaml -svc=samples/helloworld/helloworld.yaml) -n bar