Como usar pacotes do sistema

Neste tutorial, mostramos como criar um serviço personalizado do Cloud Run for Anthos no Google Cloud 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
  • Gravar, criar e implantar um serviço Cloud Run para Anthos no Google Cloud
  • Usar o utilitário Graphviz dot para gerar diagramas
  • Testar o serviço publicando um diagrama de sintaxe DOT da coleção ou sua própria criação

Custos

Neste tutorial, usamos componentes do Cloud Platform que podem ser cobrados, incluindo estes:

Use a Calculadora de preços para gerar uma estimativa de custo com base no uso previsto.

Usuários novos do Cloud Platform podem ter direito a uma avaliação gratuita.

Antes de começar

  1. Faça login na sua conta do Google.

    Se você ainda não tiver uma, inscreva-se.

  2. No Console do Google Cloud, na página do seletor de projetos, selecione ou crie um projeto do Google Cloud.

    Acessar a página do seletor de projetos

  3. Verifique se o faturamento está ativado para seu projeto na nuvem. Saiba como confirmar se o faturamento está ativado para o projeto.

  4. Ative a API Cloud Run for Anthos no Google Cloud
  5. Instale e inicie o SDK do Cloud.
  6. Instale o componente kubectl:
    gcloud components install kubectl
  7. Instale o componente beta:
    gcloud components install beta
  8. Atualize os componentes:
    gcloud components update
  9. Instale o curl (em inglês) para testar o serviço
  10. Crie um novo cluster usando as instruções em Como configurar o Cloud Run for Anthos no Google Cloud.

Como configurar padrões da gcloud

Para configurar a gcloud com os padrões do serviço do Cloud Run for Anthos no Google Cloud:

  1. Defina o projeto padrão:

    gcloud config set project PROJECT_ID

    Substitua PROJECT_ID pelo nome do projeto que você usou neste tutorial.

  2. Configure a gcloud para o cluster:

    gcloud config set kuberun/cluster CLUSTER-NAME
    gcloud config set kuberun/cluster_location REGION

    Substitua:

    • CLUSTER-NAME pelo nome que você usou para o cluster;
    • REGION pelo local do cluster compatível de sua escolha.

Como recuperar a amostra de código

Para recuperar a amostra de código para uso, siga estas etapas:

  1. 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 (em inglês) como um arquivo ZIP e extraí-lo.

  2. Altere para o diretório que contém o código de amostra do Cloud Run for Anthos no Google Cloud:

    Node.js

    cd nodejs-docs-samples/kuberun/system-package/

    Python

    cd python-docs-samples/kuberun/system-package/

    Go

    cd golang-samples/kuberun/system_package/

    Java

    cd java-docs-samples/kuberun/system-package/

Como visualizar a arquitetura

A arquitetura básica é assim:

Diagrama que mostra o fluxo de solicitações do usuário para o serviço da Web para o utilitário graphviz
    dot.
Para a fonte do diagrama, consulte a descrição do DOT

O usuário faz uma solicitação HTTP para o serviço do Cloud Run for Anthos no Google Cloud, 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.

  1. Abra o Dockerfile em um editor.

  2. Procure uma instrução Dockerfile RUN. Essa instrução permite executar comandos do shell arbitrários para modificar o ambiente. Se o Dockerfile tiver vários estágios, identificados ao encontrar várias instruções FROM, 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
    RUN apt-get update -y && apt-get install -y \
      graphviz \
      && apt-get clean
    Alpine
    O Alpine requer um segundo pacote para oferecer compatibilidade com fontes.
    RUN apk --no-cache add graphviz ttf-ubuntu-font-family

    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 de node, poderá encontrar a documentação e o Dockerfile pai no Docker Hub (em inglês).

  3. 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

app.get('/diagram.png', (req, res) => {
  try {
    const image = createDiagram(req.query.dot);
    res.setHeader('Content-Type', 'image/png');
    res.setHeader('Content-Length', image.length);
    res.setHeader('Cache-Control', 'public, max-age=86400');
    res.send(image);
  } catch (err) {
    console.error(`error: ${err.message}`);
    const errDetails = (err.stderr || err.message).toString();
    if (errDetails.includes('syntax')) {
      res.status(400).send(`Bad Request: ${err.message}`);
    } else {
      res.status(500).send('Internal Server Error');
    }
  }
});

Python

@app.route("/diagram.png", methods=["GET"])
def index():
    # Takes an HTTP GET request with query param dot and
    # returns a png with the rendered DOT diagram in a HTTP response.
    try:
        image = create_diagram(request.args.get("dot"))
        response = make_response(image)
        response.headers.set("Content-Type", "image/png")
        return response

    except Exception as e:
        print("error: {}".format(e))

        # If no graphviz definition or bad graphviz def, return 400
        if "syntax" in str(e):
            return "Bad Request: {}".format(e), 400

        return "Internal Server Error", 500

Go


// diagramHandler renders a diagram using HTTP request parameters and the dot command.
func diagramHandler(w http.ResponseWriter, r *http.Request) {
	if r.Method != http.MethodGet {
		log.Printf("method not allowed: %s", r.Method)
		http.Error(w, fmt.Sprintf("HTTP Method %s Not Allowed", r.Method), http.StatusMethodNotAllowed)
		return
	}

	q := r.URL.Query()
	dot := q.Get("dot")
	if dot == "" {
		log.Print("no graphviz definition provided")
		http.Error(w, "Bad Request", http.StatusBadRequest)
		return
	}

	// Cache header must be set before writing a response.
	w.Header().Set("Cache-Control", "public, max-age=86400")

	input := strings.NewReader(dot)
	if err := createDiagram(w, input); err != nil {
		log.Printf("createDiagram: %v", err)
		// Do not cache error responses.
		w.Header().Del("Cache-Control")
		if strings.Contains(err.Error(), "syntax") {
			http.Error(w, "Bad Request: DOT syntax error", http.StatusBadRequest)
		} else {
			http.Error(w, "Internal Server Error", http.StatusInternalServerError)
		}
	}
}

Java

get(
    "/diagram.png",
    (req, res) -> {
      InputStream image = null;
      try {
        String dot = req.queryParams("dot");
        image = createDiagram(dot);
        res.header("Content-Type", "image/png");
        res.header("Content-Length", Integer.toString(image.available()));
        res.header("Cache-Control", "public, max-age=86400");
      } catch (Exception e) {
        if (e.getMessage().contains("syntax")) {
          res.status(400);
          return String.format("Bad Request: %s", e.getMessage());
        } else {
          res.status(500);
          return "Internal Server Error";
        }
      }
      return image;
    });

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

// Generate a diagram based on a graphviz DOT diagram description.
const createDiagram = dot => {
  if (!dot) {
    throw new Error('syntax: no graphviz definition provided');
  }

  // Adds a watermark to the dot graphic.
  const dotFlags = [
    '-Glabel="Made on KubeRun"',
    '-Gfontsize=10',
    '-Glabeljust=right',
    '-Glabelloc=bottom',
    '-Gfontcolor=gray',
  ].join(' ');

  const image = execSync(`/usr/bin/dot ${dotFlags} -Tpng`, {
    input: dot,
  });
  return image;
};

Python

def create_diagram(dot):
    # Generates a diagram based on a graphviz DOT diagram description.
    if not dot:
        raise Exception("syntax: no graphviz definition provided")

    dot_args = [  # These args add a watermark to the dot graphic.
        "-Glabel=Made on KubeRun",
        "-Gfontsize=10",
        "-Glabeljust=right",
        "-Glabelloc=bottom",
        "-Gfontcolor=gray",
        "-Tpng",
    ]

    # Uses local `dot` binary from Graphviz:
    # https://graphviz.gitlab.io
    image = subprocess.run(
        ["dot"] + dot_args, input=dot.encode("utf-8"), stdout=subprocess.PIPE
    ).stdout

    if not image:
        raise Exception("syntax: bad graphviz definition provided")
    return image

Go


// createDiagram generates a diagram image from the provided io.Reader written to the io.Writer.
func createDiagram(w io.Writer, r io.Reader) error {
	stderr := new(bytes.Buffer)
	args := []string{
		"-Glabel=Made on KubeRun",
		"-Gfontsize=10",
		"-Glabeljust=right",
		"-Glabelloc=bottom",
		"-Gfontcolor=gray",
		"-Tpng",
	}
	cmd := exec.Command("/usr/bin/dot", args...)
	cmd.Stdin = r
	cmd.Stdout = w
	cmd.Stderr = stderr

	if err := cmd.Run(); err != nil {
		return fmt.Errorf("exec(%s) failed (%v): %s", cmd.Path, err, stderr.String())
	}

	return nil
}

Java

// Generate a diagram based on a graphviz DOT diagram description.
public static InputStream createDiagram(String dot) {
  if (dot == null || dot.isEmpty()) {
    throw new NullPointerException("syntax: no graphviz definition provided");
  }
  // Adds a watermark to the dot graphic.
  List<String> args = new ArrayList<String>();
  args.add("/usr/bin/dot");
  args.add("-Glabel=\"Made on KubeRun\"");
  args.add("-Gfontsize=10");
  args.add("-Glabeljust=right");
  args.add("-Glabelloc=bottom");
  args.add("-Gfontcolor=gray");
  args.add("-Tpng");

  StringBuilder output = new StringBuilder();
  InputStream stdout = null;
  try {
    ProcessBuilder pb = new ProcessBuilder(args);
    Process process = pb.start();
    OutputStream stdin = process.getOutputStream();
    stdout = process.getInputStream();
    // The Graphviz dot program reads from stdin.
    Writer writer = new OutputStreamWriter(stdin, "UTF-8");
    writer.write(dot);
    writer.close();
    process.waitFor();
  } catch (Exception e) {
    System.out.println(e);
  }
  return stdout;
}

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 o código, crie com o Cloud Build, faça o upload para o Container Registry e implante no Cloud Run for Anthos no Google Cloud:

  1. Execute o comando a seguir para criar o contêiner e publicar no Container Registry.

    Node.js

    gcloud builds submit --tag gcr.io/PROJECT_ID/graphviz

    PROJECT_ID é o ID do projeto do GCP e graphviz é o nome que você quer dar ao serviço.

    Após a conclusão, você verá uma mensagem de SUCESSO contendo 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

    PROJECT_ID é o ID do projeto do GCP e graphviz é o nome que você quer dar ao serviço.

    Após a conclusão, você verá uma mensagem de SUCESSO contendo 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

    PROJECT_ID é o ID do projeto do GCP e graphviz é o nome que você quer dar ao serviço.

    Após a conclusão, você verá uma mensagem de SUCESSO contendo 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.

    1. Usando o Dockerfile, configure e crie uma imagem base com os pacotes do sistema instalados para substituir a imagem base padrão do Jib:

      # Use the Official OpenJDK image for a lean production stage of our multi-stage build.
      # https://hub.docker.com/r/adoptopenjdk/openjdk11/
      FROM adoptopenjdk/openjdk11:alpine
      
      RUN apk --no-cache add graphviz ttf-ubuntu-font-family
      gcloud builds submit --tag gcr.io/PROJECT_ID/graphviz-base

      PROJECT_ID é o ID do projeto do GCP.

    2. Crie seu contêiner final com o Jib e publique no Container Registry:

      <plugin>
        <groupId>com.google.cloud.tools</groupId>
        <artifactId>jib-maven-plugin</artifactId>
        <version>2.7.0</version>
        <configuration>
          <from>
            <image>gcr.io/PROJECT_ID/graphviz-base</image>
          </from>
          <to>
            <image>gcr.io/PROJECT_ID/graphviz</image>
          </to>
        </configuration>
      </plugin>
      mvn compile jib:build \
       -Dimage=gcr.io/PROJECT_ID/graphviz \
       -Djib.from.image=gcr.io/PROJECT_ID/graphviz-base

      PROJECT_ID é o ID do projeto do GCP.

  2. Implante usando o comando a seguir:

    gcloud kuberun core services update graphviz-web --create-if-missing --image gcr.io/PROJECT_ID/graphviz

    PROJECT_ID é o ID do projeto do GCP, graphviz é o nome do contêiner acima e graphviz-web é o nome do serviço.

    Aguarde até que a implantação esteja concluída. Isso pode levar cerca de 30 segundos.

  3. 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.

  1. Envie uma solicitação HTTP para o serviço.

    É possível incorporar o diagrama em uma página da Web:

    1. Para receber o IP externo do gateway de entrada do Istio:
      kubectl get svc istio-ingress -n gke-system
      
      A saída resultante é algo semelhante a:
      NAME            TYPE           CLUSTER-IP     EXTERNAL-IP  PORT(S)
      istio-ingress   LoadBalancer   XX.XX.XXX.XX   pending      80:32380/TCP,443:32390/TCP,32400:32400/TCP
      
      O EXTERNAL-IP do balanceador de carga é o endereço IP que você precisa usar.
    2. Execute um comando curl usando este endereço EXTERNAL-IP no URL. Não inclua o protocolo (por exemplo: http://) em SERVICE_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
  2. Abra o arquivo diagram.png resultante em qualquer aplicativo compatível com arquivos PNG, como o Chrome.

    A aparência será semelhante a esta:

    Diagrama mostrando o fluxo de estágios:
codificação > criação > implantação > execução.
    Fonte: descrição DOT

É possível explorar uma pequena coleção de descrições de diagrama prontas (em inglês).

  1. Copie o conteúdo do arquivo .dot selecionado.
  2. 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

Limpeza

Se você criou um novo projeto para este tutorial, exclua o projeto. Se você usou um projeto atual e quer mantê-lo sem as alterações incluídas neste tutorial, exclua os recursos criados para o tutorial.

Como excluir o projeto

O jeito mais fácil de evitar cobranças é excluindo o projeto que você criou para o tutorial.

Para excluir o projeto:

  1. No Console do Cloud, acesse a página Gerenciar recursos:

    Acessar "Gerenciar recursos"

  2. Na lista de projetos, selecione o projeto que você quer excluir e clique em Excluir .
  3. Na caixa de diálogo, digite o ID do projeto e clique em Encerrar para excluí-lo.

Como excluir recursos do tutorial

  1. Exclua o serviço do Cloud Run para Anthos no Google Cloud que você implantou neste tutorial:

    gcloud kuberun core services delete SERVICE-NAME

    SERVICE-NAME é o nome escolhido do serviço.

    Também é possível excluir o Cloud Run para Anthos nos serviços do Google Cloud no Console do Google Cloud.

  2. Remova as configurações padrão da gcloud que você adicionou durante a configuração do tutorial:

     gcloud config unset kuberun/cluster
     gcloud config unset kuberun/cluster_location
    
  3. Remova a configuração do projeto:

     gcloud config unset project
    
  4. Exclua outros recursos do Google Cloud criados neste tutorial:

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.
    • Veja outro exemplo de pacote do sistema em Processamento de imagens.
  • Teste outros recursos do Google Cloud. Veja nossos tutoriais.