Objetivos

• Implementar um app de banco de dados Python conteinerizado com suporte a diversos locatários e acesso seguro
• Integrar o App ID como provedor de autenticação baseado no OpenID Connect
• Configurar a coleta serverless automatizada de estatísticas de tráfego do GitHub

Antes de Iniciar

Este tutorial requer:

• CLI do IBM Cloud,
  • Plug-in do IBM Cloud Code Engine,
  • Plug-in do IBM Cloud® Container Registry,
• uma conta do GitHub.

É possível executar as seções que requerem um shell no IBM® Cloud Shell.

Você encontrará instruções para fazer download e instalar essas ferramentas para o seu ambiente operacional no guia Introdução aos tutoriais.

Configuração de serviço e ambiente (shell)

Nesta seção, você configura os serviços necessários e prepara o ambiente. Tudo isso pode ser realizado no ambiente de shell (terminal).

1. Se você não estiver conectado, use ibmcloud login ou ibmcloud login --sso para fazer login interativamente.

2. St o grupo de recursos e região executando o comando ibmcloud target.

   RESOURCE_GROUP_NAME=Default
   REGION=us-south
   ibmcloud target -r $REGION -g $RESOURCE_GROUP_NAME
   

3. Crie uma instância do IBM Db2 SaaS com o plano grátis (lite) e nomeia-a como ghstatsDB.

   ibmcloud resource service-instance-create ghstatsDB dashdb-for-transactions free $REGION
   

4. Crie uma instância do serviço App ID. Use ghstatsAppID como o nome e o plano Camada graduada.

   ibmcloud resource service-instance-create ghstatsAppID appid graduated-tier $REGION
   

5. Inclua um novo namespace ghstats no IBM Cloud® Container Registry. Você irá usá-lo para referenciar imagens de contêiner. Há um registro global, bem como registros regionais. Use o registro global

   ibmcloud cr region-set global
   NAMESPACE=ghstatsYourInitials
   ibmcloud cr namespace-add $NAMESPACE
   

Preparação do Code Engine (shell)

Com os serviços provisionados e a configuração geral concluída, o próximo passo é criar o projeto do Code Engine, criar uma imagem de contêiner para o app e implementá-la.

1. Crie um projeto do Code Engine denominado ghstats. O comando o configura automaticamente como o contexto atual do Code Engine.

   ibmcloud ce project create --name ghstats
   

2. Crie uma configuração de construção do Code Engine, ou seja, configure o projeto para construir a imagem de contêiner para você. Ele usa o código do repositório do GitHub para este tutorial e armazena a imagem no registro no namespace criado anteriormente usando as informações do usuário registrado.

   ibmcloud ce build create --name ghstats-build --source https://github.com/IBM-Cloud/github-traffic-stats  --context-dir /backend --commit master --image private.icr.io/$NAMESPACE/codeengine-ghstats
   

3. Observe que o comando de criação de construção teve o efeito colateral de criar um segredo de acesso de registro que permitirá que o projeto grave e leia o IBM Cloud® Container Registry.

   ibmcloud ce registry list
   

4. Em seguida, execute o processo de construção real.

   ibmcloud ce buildrun submit --build ghstats-build
   

   A saída indica mais comandos para correr para seguir os logs de status da construção à medida que ele progride. Algo como:

   ibmcloud ce buildrun logs -f -n ghstats-build-run-123456-123456789
   

Implementar o app (shell)

Uma vez que a construção esteja pronta, é possível usar a imagem de contêiner para implementar o app e, em seguida, ligar os serviços provisionados anteriormente.

1. Implementar o app significa criar um app Code Engine denominado ghstats-app. Ele extrai a imagem do registro e namespace determinados.

   ibmcloud ce app create --name ghstats-app --image private.icr.io/$NAMESPACE/codeengine-ghstats:latest --registry-secret ce-auto-icr-private-global
   

   Uma vez que o app tenha sido implementado, é possível verificar se ele está disponível na URL mostrada na saída. O app não foi configurado e, portanto, ainda não é utilizável. É possível verificar o status de implementação usando ibmcloud ce app list ou obter detalhes executando ibmcloud ce app get --name ghstats-app.

   Por padrão, o ajuste de escala mínimo é 0 (zero). Isso significa que o Code Engine reduz as instâncias em execução a zero se não há carga de trabalho no app. Isso economiza custos, mas requer um pequeno reinício de app ao aumentar a capacidade do zero novamente. É possível evitar isso usando o parâmetro --min 1 ao criar ou atualizar o app.

2. Para utilizar os serviços provisionados, é preciso ligá-los ao app. Primeiro, ligue o IBM Db2 SaaS, em seguida, o App ID:

   ibmcloud ce application bind --name ghstats-app --service-instance ghstatsDB
   

   ibmcloud ce application bind --name ghstats-app --service-instance ghstatsAppID
   

   Cada application bind cria os recursos e relacionamentos foldevidos:

   1. Um ID IAM Service.
   2. Uma chave API IAM é criada no ID IAM Service.
   3. Uma chave de serviço de recursos. Estes são chamados (credenciais de serviço no console IBM Cloud. Tente o seguinte comando para exibir a entrada App ID:

   ibmcloud resource service-keys  --instance-name ghstatsAppID
   

   Em vez de ligar os serviços ao app, também é possível usar segredos ou configmaps.. Eles podem ser preenchidos com valores armazenados em arquivos ou transmitidos como literais. Um arquivo de amostra para segredos e instruções relacionadas estão no repositório do GitHub para este tutorial.

Configuração do App ID e do GitHub (navegador)

As etapas a seguir são todas executadas usando seu navegador da Internet. Primeiro, você configura o App ID para usar o Cloud Directory e para trabalhar com o app. Depois disso, você cria um token de acesso GitHub. Ele é necessário para o app recuperar os dados de tráfego.

1. Na IBM Cloud® Lista de recursos, abra a visão geral de seus serviços. Localize a instância do serviço App ID na seção Serviços. Clique em sua entrada para abrir os detalhes.

2. No painel de serviço, clique em Gerenciar autenticação no menu no lado esquerdo. Ele traz uma lista de provedores de identidade disponíveis, como Facebook, Google, Federação SAML 2.0 e o Cloud Directory. Alterne o Cloud Directory para Ativado, todos os outros provedores para Desativado.

   Você pode desejar configurar as regras de senha Multi-Factor Authentication (MFA) e avançada. Elas não são discutidas como parte deste tutorial.

3. Clique na guia Configurações de autenticação no mesmo diálogo. Em Incluir URLs de redirecionamento da web, insira a URL de seu aplicativo + /redirect_uri, por exemplo https://ghstats-app.56ab78cd90ef.us-south.codeengine.appdomain.cloud/redirect_uri.

   Para testar o app localmente, a URL de redirecionamento é http://127.0.0.1:5000/redirect_uri. É possível configurar múltiplas URLs de redirecionamento. Para testar o app localmente, copie .env.local.template para .env, adapte-o e inicie o app usando python3 ghstats.py.

4. No menu à esquerda, expanda Cloud Directory e clique em Usuários. Ele abre a lista de usuários no Cloud Directory. Clique no botão Criar usuário para incluir-se como o primeiro usuário. Agora você está pronto para configurar o serviço App ID.

5. No navegador, acesse Github.com e vá para Settings -> Developer settings -> Personal access tokens. Clique no botão Generate new token (clássico). Digite GHStats Tutorial para a Nota. Depois disso, ative public_repo na categoria repo e read:org em admin:org. Agora, na parte inferior dessa página, clique em Gerar token. O novo token de acesso é exibido na próxima página. Ele é necessário durante a configuração do aplicativo a seguir.

   

Configurar e testar o app Python

Após a preparação, você configura e testa o app. O aplicativo foi escrito em Python usando o popular microframework Flask. É possível incluir repositórios para coleta de estatísticas ou removê-los. É possível acessar os dados de tráfego em uma visualização tabular ou como um gráfico de linha.

1. Em um navegador, abra o URI do app implementado. Você deve ver uma página de boas-vindas.

   

2. No navegador, inclua /admin/initialize-app para o URI e acesse a página. Ele é usado para inicializar o aplicativo e seus dados. Clique no botão Iniciar a inicialização. Isso levará você a uma página de configuração protegida por senha. O endereço de e-mail com o qual você efetua login é obtido como identificação para o administrador do sistema. Use o endereço de e-mail e a senha que você configurou anteriormente.

3. Na página de configuração, insira um nome (ele é usado para saudações), seu nome do usuário do GitHub e o token de acesso que você gerou antes. Clique em Inicializar. Isso cria as tabelas de banco de dados e insere alguns valores de configuração. Por fim, ele cria registros de banco de dados para o administrador do sistema e um locatário.

   

4. Uma vez feito, você é levado para a lista de repositórios gerenciados. Agora é possível incluir repositórios fornecendo o nome da conta ou da organização do GitHub e o nome do repositório. Depois de inserir os dados, clique em Incluir repositório. O repositório, juntamente com um identificador recém-designado, deve aparecer na tabela. É possível remover repositórios do sistema inserindo seu ID e clicando em Excluir repositório.

   

5. Para testes, clique em Administração, em seguida, em Coletar estatísticas. Isso recupera os dados de tráfego on demand. Depois disso, clique em Repositórios e Tráfego diário. Os dados coletados devem ser exibidos.

   

Configurar recuperação de dados diários (shell)

Com o app instalado e configurado, a última parte é iniciar a recuperação diária dos dados de tráfego do GitHub. Você vai criar uma assinatura cron. Semelhante a um trabalho cron, o aplicativo assina eventos no cronograma especificado (eventing).

1. Crie uma assinatura cron ghstats-daily com um planejamento diário às 6h UTC com um evento POST no caminho /collectStats. Substitua SECRET_TOKEN_AS_IDENTIFIER pelo seu valor de segredo escolhido. Ele é usado para identificar o fornecedor do evento para o app.

   ibmcloud ce subscription cron create --name ghstats-daily --destination ghstats-app --path /collectStats --schedule '0 6 * * *' --data '{"token":"SECRET_TOKEN_AS_IDENTIFIER"}' --content-type application/json
   

2. Para tornar o token secreto conhecido para o app, atualize o app. Substitua SECRET_TOKEN_AS_IDENTIFIER pelo valor que você escolheu na etapa anterior.

   ibmcloud ce app update --name ghstats-app --registry-secret usicr --env EVENT_TOKEN=SECRET_TOKEN_AS_IDENTIFIER
   

   Isso cria uma nova revisão de app. É possível verificar se os eventos foram recebidos e processados pelo app ao navegar no app até Administração e, em seguida, Log do sistema.

   O comando acima cria um planejamento para 6h UTC diariamente. Para verificar diretamente se a criação de eventos funciona, escolha um horário poucos minutos após o seu horário atual, convertido para UTC.

Conclusões

Neste tutorial, você implementou um app serverless no IBM Cloud Code Engine. A origem do app é obtida de um repositório GitHub. Você instruiu o Code Engine a construir a imagem de contêiner e armazená-la no IBM Cloud® Container Registry. Em seguida, ela foi extraída de lá e implementada como contêiner. O app está ligado aos serviços da IBM Cloud.

O app e a criação de eventos associada permitem recuperar automaticamente dados de tráfego para repositórios GitHub. As informações sobre esses repositórios, incluindo o token de acesso específico do locatário, são armazenadas em um banco de dados SQL (IBM Db2 Warehouse SaaS). Esse banco de dados é usado pelo app Python para gerenciar usuários, repositórios e para apresentar as estatísticas de tráfego. Os usuários podem ver as estatísticas de tráfego em tabelas pesquisáveis ou visualizadas em um gráfico de linha simples (veja imagem abaixo). Também é possível fazer download da lista de repositórios e dos dados de tráfego como arquivos CSV.

Segurança: gire credenciais de serviço

Se você usar essa solução em produção, será necessário girar as credenciais de serviço em uma base regular. Muitas políticas de segurança têm um requisito para mudar senhas e credenciais a cada 90 dias ou com frequência semelhante.

É possível recriar e, assim, girar as credenciais para os serviços ligados ao app, desvinculando e, em seguida, ligando os serviços novamente. Ao usar segredos em vez de ligações de serviço, você até tem mais opções, primeiro recriando as chaves de serviço, em seguida, atualizando os segredos e, como última etapa, atualizando o app.

Remover recursos

Para limpar os recursos usados para este tutorial, é possível excluir o projeto e os serviços relacionados.

1. Desvincule os serviços provisionados. Primeiro exibir as ligações então exclua-as por Nomes de Ligações de Serviços (FIRST e SECOND abaixo são da saída get)

   ibmcloud ce application get --name ghstats-app
   

   ibmcloud ce application unbind --name ghstats-app --binding ghstats-app-ce-service-binding-FIRST
   

   ibmcloud ce application unbind --name ghstats-app --binding ghstats-app-ce-service-binding-SECOND
   

2. Excluir o projeto e seus componentes.

   ibmcloud ce project delete --name ghstats --hard -f
   

3. Excluir os serviços:

   ibmcloud resource service-instance-delete -f ghstatsDB
   

   ibmcloud resource service-instance-delete -f ghstatsAppID
   

4. Exclua o espaço de nome Container Registry

   ibmcloud cr namespace-rm $NAMESPACE -f
   

5. Excluir o token Github.com

Dependendo do recurso, ele não é excluído imediatamente, mas retido (por padrão por 7 dias). É possível recuperar o recurso excluindo-o permanentemente ou restaurando-o dentro do período de retenção. Consulte este documento sobre como usar a recuperação de recurso.

Expandir o tutorial

Deseja incluir ou mudar este tutorial? Aqui estão algumas ideias:

• Expanda o app para suporte de diversos locatários.
• Use provedores de identidade social.
• Inclua um selecionador de data na página de estatísticas para filtrar dados exibidos.
• Use uma página de login customizado para o App ID.

Conteúdo relacionado

Aqui estão os links para informações adicionais sobre os tópicos abordados neste tutorial. O aplicativo em si está disponível neste repositório GitHub.

Documentação:

• Documentação do App ID
• IBM Db2 SaaS