Neste tutorial, mostramos como criar um serviço do Knative serving
personalizado que transforma um parâmetro de entrada de descrição de gráfico em um diagrama no formato de
imagem PNG
. Ele usa o Graphviz (em inglês) que
é instalado como um pacote de sistema no ambiente de contêiner do serviço.
O Graphviz é usado com utilitários de linha de comando para exibir solicitações.
Objetivos
- Gravar e criar um contêiner personalizado com um Dockerfile
- Escrever, criar e implantar um serviço do Knative serving
- Usar o utilitário Graphviz dot para gerar diagramas
- Testar o serviço publicando um diagrama de sintaxe DOT da coleção ou criado por você
Custos
Neste documento, você usará os seguintes componentes faturáveis do Google Cloud:
Para gerar uma estimativa de custo baseada na projeção de uso deste tutorial, use a calculadora de preços.
Antes de começar
- Neste tutorial, presumimos que você tenha o Knative serving instalado e configurado no cluster.
- Verifique se o ambiente da linha de comando está configurado e se as ferramentas estão atualizadas.
Como recuperar o exemplo de código
Para recuperar o exemplo de código para uso, siga estas etapas:
Clone o repositório do aplicativo de amostra na máquina local:
Node.js
git clone https://github.com/GoogleCloudPlatform/nodejs-docs-samples.git
Outra alternativa é fazer o download da amostra como um arquivo ZIP e extraí-lo.
Python
git clone https://github.com/GoogleCloudPlatform/python-docs-samples.git
Outra alternativa é fazer o download da amostra como um arquivo ZIP e extraí-lo.
Go
git clone https://github.com/GoogleCloudPlatform/golang-samples.git
Outra alternativa é fazer o download da amostra como um arquivo ZIP e extraí-lo.
Java
git clone https://github.com/GoogleCloudPlatform/java-docs-samples.git
Outra alternativa é fazer o download da amostra como um arquivo ZIP e extraí-lo.
Mude para o diretório que contém o código de amostra de Knative serving:
Node.js
cd nodejs-docs-samples/run/system-package/
Python
cd python-docs-samples/run/system-package/
Go
cd golang-samples/run/system_package/
Java
cd java-docs-samples/run/system-package/
Como visualizar a arquitetura
A arquitetura básica é assim:
O usuário faz uma solicitação HTTP para o serviço Knative serving, que executa um utilitário Graphviz para transformar a solicitação em uma imagem. Essa imagem é entregue ao usuário como a resposta HTTP.
Como entender o código
Como definir a configuração do ambiente com o Dockerfile
O Dockerfile
é específico para a linguagem e o ambiente operacional base, como o Ubuntu, que o serviço usará.
Para esse serviço, um ou mais pacotes de sistema não disponíveis por padrão são requisitados.
Abra o
Dockerfile
em um editor.Procure uma instrução
Dockerfile
RUN
. Essa instrução permite executar comandos do shell arbitrários para modificar o ambiente. Se oDockerfile
tiver vários estágios, identificados ao encontrar várias instruçõesFROM
, ele será encontrado no último estágio.Os pacotes específicos necessários e o mecanismo para instalá-los variam de acordo com o sistema operacional declarado dentro do contêiner.
Para ver instruções sobre o sistema operacional ou sobre a imagem base, clique na guia adequada.
Debian/Ubuntu Alpine O Alpine requer um segundo pacote para oferecer compatibilidade com fontes.Para determinar o sistema operacional da imagem do contêiner, verifique o nome na instrução
FROM
ou um README associado à imagem base. Por exemplo, se você estender denode
, poderá encontrar a documentação e oDockerfile
pai no Docker Hub (em inglês).Teste sua personalização criando a imagem. Use o
docker build
localmente ou o Cloud Build.
Como processar as solicitações recebidas
O serviço de amostra usa parâmetros da solicitação HTTP recebida para invocar uma chamada do sistema que executa o comando do utilitário dot
adequado.
No manipulador HTTP abaixo, um parâmetro de entrada de descrição de gráfico é extraído da variável querystring dot
.
As descrições de gráficos podem incluir caracteres que precisam ser codificados em URL (em inglês) para uso em uma querystring.
Node.js
Python
Go
Java
Será preciso diferenciar entre erros internos do servidor e entradas inválidas
do usuário. Este exemplo de serviço retorna um erro interno do servidor para todos os erros de linha de comando de ponto, a menos que a mensagem de erro contenha a string syntax
, que indica um problema de entrada do usuário.
Como gerar um diagrama
A lógica central da geração de diagramas usa a ferramenta de linha de comando do dot para processar o parâmetro de entrada da descrição do gráfico em um diagrama no formato de imagem PNG.
Node.js
Python
Go
Java
Como criar um serviço seguro
Quaisquer vulnerabilidades na ferramenta dot
são possíveis pontos de fragilidade do serviço da Web. É possível atenuar isso usando versões atualizadas do pacote graphviz
com a recriação regular da imagem do contêiner.
Se você estende a amostra atual para aceitar a entrada do usuário como parâmetros de linha de comando, proteja-se contra ataques de injeção de comandos (em inglês). Algumas das formas de evitar ataques por injeção incluem:
- o mapeamento de entradas para um dicionário de parâmetros compatíveis;
- a validação de entradas para ver se correspondem a um intervalo de valores seguros conhecidos, talvez usando expressões regulares;
- o escape de entradas para garantir que a sintaxe do shell não seja avaliada.
Como enviar o código
Para enviar seu código, crie com o Cloud Build, faça o upload para o Container Registry e implante no Knative serving:
Execute o comando a seguir para criar seu contêiner e publicar no Container Registry.
Node.js
gcloud builds submit --tag gcr.io/PROJECT_ID/graphviz
Em que PROJECT_ID é o ID do projeto do Google Cloud e
graphviz
é o nome que você quer dar ao seu serviço.Após a conclusão, você receberá uma mensagem de SUCESSO com o ID, a hora da criação e o nome da imagem. A imagem é armazenada no Container Registry e poderá ser reutilizada, se você quiser.
Python
gcloud builds submit --tag gcr.io/PROJECT_ID/graphviz
Em que PROJECT_ID é o ID do projeto do Google Cloud e
graphviz
é o nome que você quer dar ao seu serviço.Após a conclusão, você receberá uma mensagem de SUCESSO com o ID, a hora da criação e o nome da imagem. A imagem é armazenada no Container Registry e poderá ser reutilizada, se você quiser.
Go
gcloud builds submit --tag gcr.io/PROJECT_ID/graphviz
Em que PROJECT_ID é o ID do projeto do Google Cloud e
graphviz
é o nome que você quer dar ao seu serviço.Após a conclusão, você receberá uma mensagem de SUCESSO com o ID, a hora da criação e o nome da imagem. A imagem é armazenada no Container Registry e poderá ser reutilizada, se você quiser.
Java
Esta amostra usa o Jib (em inglês) para criar imagens do Docker usando ferramentas comuns do Java. O Jib otimiza builds de contêiner sem a necessidade de um Dockerfile ou de ter o Docker (em inglês) instalado. Saiba mais sobre como criar contêineres Java com o Jib.Usando o Dockerfile, configure e crie uma imagem base com os pacotes do sistema instalados para substituir a imagem base padrão do Jib:
gcloud builds submit --tag gcr.io/PROJECT_ID/graphviz-base
em que PROJECT_ID é o ID do projeto no Google Cloud.
Crie seu contêiner final com o Jib e publique no Container Registry:
mvn compile jib:build \ -Dimage=gcr.io/PROJECT_ID/graphviz \ -Djib.from.image=gcr.io/PROJECT_ID/graphviz-base
em que PROJECT_ID é o ID do projeto no Google Cloud.
Implante usando o seguinte comando:
gcloud run deploy graphviz-web --create-if-missing --image gcr.io/PROJECT_ID/graphviz
Em que PROJECT_ID é o ID do projeto do Google Cloud e
graphviz
é o nome do contêiner acima egraphviz-web
é o nome do serviço.Aguarde até que a implantação esteja concluída. Isso pode levar cerca de 30 segundos.
Se você quer implantar uma atualização de código no serviço, repita as etapas anteriores. Cada implantação em um serviço cria uma nova revisão e inicia automaticamente o tráfego de serviço quando estiver pronto.
Teste
Teste seu serviço enviando solicitações HTTP POST
com descrições de sintaxe DOT na carga útil da solicitação.
Envie uma solicitação HTTP para o serviço.
É possível incorporar o diagrama em uma página da Web:
-
Para conseguir o IP externo do balanceador de carga, execute o seguinte comando:
kubectl get svc istio-ingressgateway -n ASM-INGRESS-NAMESPACE
Substitua ASM-INGRESS-NAMESPACE pelo namespace em que a entrada do Cloud Service Mesh está localizada. Especifique
istio-system
se você instalou o Cloud Service Mesh usando a configuração padrão.A resposta resultante será semelhante a:
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) istio-ingressgateway LoadBalancer XX.XX.XXX.XX pending 80:32380/TCP,443:32390/TCP,32400:32400/TCP
em que o valor EXTERNAL-IP é o endereço IP externo do balanceador de carga.
Execute um comando curl usando este endereço
EXTERNAL-IP
no URL. Não inclua o protocolo (por exemplo:http://
) emSERVICE_DOMAIN
.curl -G -H "Host: SERVICE_DOMAIN" http://EXTERNAL-IP/diagram.png \ --data-urlencode "dot=digraph Run { rankdir=LR Code -> Build -> Deploy -> Run }" \ > diagram.png
-
Abra o arquivo
diagram.png
resultante em qualquer aplicativo compatível com arquivosPNG
, como o Chrome.A aparência será semelhante a esta:
É possível explorar uma pequena coleção de descrições de diagrama prontas (em inglês).
- Copie o conteúdo do arquivo
.dot
selecionado. Cole-o em um comando
curl
:curl -G -H "Host: SERVICE_DOMAIN" http://EXTERNAL-IP/diagram.png \ --data-urlencode "dot=digraph Run { rankdir=LR Code -> Build -> Deploy -> Run }" \ > diagram.png
Limpar
Exclua os recursos criados para este tutorial para evitar cobranças.
Como excluir recursos do tutorial
Exclua o serviço do Knative serving que você implantou neste tutorial:
gcloud run services delete SERVICE-NAME
SERVICE-NAME é o nome escolhido do serviço.
Também é possível excluir os serviços do Knative serving no Console do Google Cloud.
Remova as configurações padrão da gcloud que você adicionou durante a configuração do tutorial:
gcloud config unset run/platform gcloud config unset run/cluster gcloud config unset run/cluster_location
Remova a configuração do projeto:
gcloud config unset project
Exclua outros recursos do Google Cloud criados neste tutorial:
- Exclua a imagem de contêiner denominada
gcr.io/<var>PROJECT_ID</var>/graphviz
do Container Registry. - Se você criou um cluster para este tutorial, exclua-o.
- Exclua a imagem de contêiner denominada
A seguir
- Teste com seu aplicativo graphviz:
- Adicione suporte para outros utilitários graphviz que aplicam algoritmos diferentes para a geração de diagramas.
- Salve diagramas no Cloud Storage. Você quer salvar a imagem ou a sintaxe do DOT?
- Implemente a proteção contra abuso de conteúdo com a API Cloud Natural Language.
- Confira arquiteturas de referência, diagramas e práticas recomendadas do Google Cloud. Confira o Centro de arquitetura do Cloud.