Tutorial: Criando um aplicativo de pilha completa com esquemas de PDK compostos

CodeCatalyst A Amazon fornece vários modelos diferentes para ajudar você a começar seus projetos rapidamente. Um projeto criado com um blueprint inclui os recursos de que você precisa, incluindo um repositório de origem, exemplo de código-fonte, fluxos de trabalho de CI/CD, relatórios de criação e teste e ferramentas integradas de controle de problemas. No entanto, às vezes você pode querer criar gradualmente um projeto ou adicionar funcionalidade a um projeto existente criado por meio de um blueprint. Você também pode fazer isso com plantas. Este tutorial demonstra como você pode começar com um único blueprint que define uma base e permite armazenar todo o código do seu projeto em um único repositório. A partir daí, você tem a flexibilidade de incorporar recursos e infraestrutura adicionais adicionando outros esquemas ao plano inicial, conforme sua conveniência. Por meio desse método básico, você pode atender a requisitos específicos em vários projetos.

Este tutorial mostra como compor vários esquemas do AWS Project Development Kit (AWS PDK) juntos para criar um aplicativo composto por um site do React, a API Smithy e a infraestrutura de CDK de suporte para implantá-lo na AWS. O AWS PDK fornece elementos básicos para padrões comuns, além de ferramentas de desenvolvimento para gerenciar e criar seus projetos. Para obter mais informações, consulte o repositório de GitHub origem do AWS PDK.

Os seguintes esquemas de PDK foram projetados para serem usados entre si para criar um aplicativo de forma combinável:

• Monorepo - Cria um projeto de nível raiz que gerencia as interdependências entre projetos dentro do monorepo. O projeto também fornece armazenamento em cache de compilação e visualização de dependências.

• API Type Safe - cria uma API que pode ser definida no Smithy ou na OpenAPI v3 e gerencia a geração de código em tempo de construção para permitir que você implemente e interaja com sua API de maneira segura. Fornece uma construção de CDK que gerencia a implantação de sua API no API Gateway e configura a validação automática de entrada.

• Site do Cloudscape React - Cria um site baseado em React criado usando o Cloudscape que vem pré-integrado ao Cognito Auth e (opcionalmente) à sua API criada, que fornece a capacidade de chamar sua API com segurança.

• Infraestrutura - Cria um projeto que configura toda a infraestrutura relacionada ao CDK necessária para implantar seu aplicativo. Ele também vem pré-configurado para gerar um diagrama baseado em seu código CDK toda vez que você cria.

• DevOps- Cria DevOps fluxos de trabalho compatíveis com construções encontradas no AWS Project Development Kit (AWS PDK).

O tutorial também inclui etapas sobre como visualizar o aplicativo implantado, convidar outros usuários para trabalhar nele e fazer alterações no código com pull requests que são automaticamente criadas e implantadas em recursos na conta conectada da AWS quando a pull request é mesclada.

Quando você cria um projeto composto por blueprints do PDK, seu projeto é criado com os seguintes recursos em um projeto: CodeCatalyst

• Um repositório de origem configurado como um monorepo.

• Um fluxo de trabalho que executa análise estática de código e verificação de licenças, além de criar e implantar o código de amostra sempre que uma alteração é feita na ramificação padrão. Um diagrama de arquitetura é gerado sempre que você faz alterações no código.

• Um quadro de problemas e uma lista de pendências que você pode usar para planejar e monitorar o trabalho.

• Um conjunto de relatórios de teste com relatórios automatizados.

Tópicos

• Pré-requisitos
• Etapa 1: criar um projeto monorepo
• Etapa 2: adicionar a API Type Safe ao projeto
• Etapa 3: Adicionar um site do Cloudscape React para o projeto
• Etapa 4: gerar a infraestrutura para implantar o aplicativo na nuvem da AWS
• Etapa 5: configurar um DevOps fluxo de trabalho para implantar seu projeto
• Etapa 6: confirme o fluxo de trabalho de lançamento e visualize seu site
• Colabore e repita o projeto PDK

Pré-requisitos

Para criar e atualizar um projeto, você deve ter concluído as tarefas da Configure e faça login em CodeCatalyst seguinte forma:

• Tenha um ID de AWS construtor para fazer login CodeCatalyst.

• Pertença a um espaço e tenha a função de administrador do espaço ou usuário avançado atribuída a você nesse espaço. Para obter mais informações, consulte Criando um espaço, Concedendo permissões de espaço aos usuários e Função de administrador de espaço.

• Tenha uma conta da AWS associada ao seu espaço e tenha a função do IAM que você criou durante a inscrição. Por exemplo, durante a inscrição, você tem a opção de escolher criar uma função de serviço com uma política de função chamada política de função CodeCatalystWorkflowDevelopmentRole- SpaceName. A função terá um nome CodeCatalystWorkflowDevelopmentRole-spaceName com um identificador exclusivo anexado. Para obter mais informações sobre a função e a política de funções, consulteEntendendo a função CodeCatalystWorkflowDevelopmentRole-spaceNamede serviço. Para obter as etapas para criar a função, consulteCriando a CodeCatalystWorkflowDevelopmentRole-spaceNamefunção para sua conta e espaço.

Etapa 1: criar um projeto monorepo

Comece com o PDK - Monorepo blueprint para criar sua base de código monorepo que atua como base, permitindo que você adicione outros blueprints PDK.

Para criar um projeto usando o blueprint PDK - Monorepo

1. Abra o CodeCatalyst console em https://codecatalyst.aws/.

2. No CodeCatalyst console, navegue até o espaço em que você deseja criar um projeto.

3. No painel do espaço, escolha Criar projeto.

4. Escolha Começar com um blueprint.

5. Escolha o blueprint PDK - Monorepo e, em seguida, escolha Avançar.

6. Em Nomear seu projeto, insira o nome que você deseja atribuir ao seu projeto e os nomes dos recursos associados. O nome deve ser exclusivo em seu espaço.

7. Em Recursos do projeto, faça o seguinte:

   1. Em Linguagem de programação primária, escolha uma linguagem na qual você deseja desenvolver o código do seu projeto. Você pode escolher TypeScript entre Java ou Python.

   2. Escolha a configuração do código

   3. No campo de entrada de texto do repositório de origem, insira o nome de um repositório de origem, que criará um novo repositório ou selecionará um repositório vinculado existente. O repositório existente deve estar vazio. Para ter mais informações, consulte Vinculando um repositório de origem.

   4. (Opcional) No menu suspenso Package Manager, escolha um gerenciador de pacotes. Isso só é necessário se você selecionou TypeScript como sua linguagem de programação principal.

8. (Opcional) Para visualizar o código que será gerado com base nas seleções de parâmetros do projeto que você fez, escolha Visualizar código em Gerar visualização do projeto.

9. (Opcional) Escolha Exibir detalhes no cartão do blueprint para ver detalhes específicos sobre o blueprint, como uma visão geral da arquitetura do blueprint, conexões e permissões necessárias e o tipo de recursos que o blueprint cria.

10. Escolha Criar projeto para criar seu projeto monorepo. O projeto de nível raiz criado gerencia as interdependências entre projetos dentro do monorepo, além de fornecer cache de compilação e gerenciamento de dependências.

    Para obter mais informações sobre esquemas de projetos, consulteCriando um projeto abrangente com CodeCatalyst plantas.

O modelo PDK - Monorepo gera apenas a base do projeto. Para criar um aplicativo viável usando o blueprint, você precisa adicionar outros blueprints de PDK, como Type Safe API, Cloudscape React Website, Infrastructure ou. DevOps Na próxima etapa, você adicionará uma API Type Safe ao projeto.

Etapa 2: adicionar a API Type Safe ao projeto

O blueprint da API PDK - Type Safe permite que você defina uma API usando o Smithy ou o OpenAI v3. Ele gera pacotes de tempo de execução a partir de sua definição de API, que incluem clientes para interagir com sua API e código do lado do servidor para implementar sua API. O blueprint também gera uma construção de CDK com segurança de tipo para cada operação de API. Você pode adicionar o blueprint a um projeto PDK monorepo existente para adicionar recursos de API ao projeto.

Para adicionar o blueprint da API PDK - Type Safe

1. No painel de navegação do seu projeto monorepo, escolha Blueprints e, em seguida, escolha Adicionar blueprint.

2. Escolha o blueprint PDK - Type Safe API e, em seguida, escolha Avançar.

3. Em Configurar blueprint, configure os parâmetros do blueprint:

   • Em Linguagem do modelo, escolha o idioma em que o modelo de API está definido.

   • No campo de entrada de texto Namespace, insira um namespace para sua API.

   • No campo de entrada de texto do nome da API, insira um nome para sua API.

   • Em Linguagem CDK, escolha seu idioma preferido para escrever a infraestrutura CDK na qual implantar a API.

   • Escolha o menu suspenso Idiomas do manipulador e, em seguida, escolha os idiomas nos quais você deseja implementar manipuladores para operações de API.

   • Escolha o menu suspenso Formatos de documentação e, em seguida, escolha os formatos que você deseja para gerar a documentação da API.

4. Na guia Alterações no código, revise as alterações propostas. A diferença exibida em uma pull request mostra as alterações em seu projeto no momento em que a pull request foi criada.

5. Quando estiver satisfeito com as alterações propostas que serão feitas quando o blueprint for aplicado, escolha Adicionar blueprint.

   Depois que uma pull request é criada, você pode adicionar comentários. Os comentários podem ser adicionados à pull request ou a linhas individuais em arquivos, bem como à pull request geral. Você pode adicionar links a recursos, como arquivos, usando o @ sinal seguido pelo nome do arquivo.

   nota

   O blueprint não será aplicado até que a pull request seja aprovada e mesclada. Para obter mais informações, consulte Analisando uma pull request e Mesclando uma pull request.

6. Na coluna Status, escolha pull request pendente para a linha do blueprint PDK - Type Safe API e, em seguida, escolha o link da pull request aberta.

7. Escolha Mesclar, escolha sua estratégia de mesclagem preferida e, em seguida, escolha Mesclar para incorporar as alterações do blueprint aplicado.

   Depois que a pull request é mesclada, uma nova packages/apis/mypdkapi pasta é gerada em seu projeto monorepo, que contém todo o código-fonte relacionado à API da sua API Type Safe configurada.

8. No painel de navegação, escolha Blueprints para confirmar se o status da API PDK - Type Safe mostra Atualizado.

Etapa 3: Adicionar um site do Cloudscape React para o projeto

O blueprint do site PDK - Cloudscape React gera um site. Você pode associar um parâmetro opcional (APIs Type Safe) para configurar automaticamente seu site para configurar clientes de tipo seguro autenticados junto com um explorador de API interativo para testar suas várias APIs.

Para adicionar o plano do site PDK - Cloudscape React

1. No painel de navegação do seu projeto monorepo, escolha Blueprints e, em seguida, escolha Adicionar blueprint.

2. Escolha o blueprint do site PDK - Cloudscape React e, em seguida, escolha Avançar.

3. Em Configurar blueprint, configure os parâmetros do blueprint:

   • No campo de entrada de texto Nome do site, insira um nome para seu site.

   • Escolha o menu suspenso Type Safe APIs e, em seguida, escolha os esquemas de API que você deseja integrar ao site. A transmissão de uma API configura clientes autenticados e adiciona as dependências necessárias, o explorador de API e outros recursos.

4. Na guia Alterações no código, revise as alterações propostas. A diferença exibida em uma pull request mostra as alterações em seu projeto no momento em que a pull request foi criada.

5. Quando estiver satisfeito com as alterações propostas que serão feitas quando o blueprint for aplicado, escolha Adicionar blueprint.

   Depois que uma pull request é criada, você pode adicionar comentários. Os comentários podem ser adicionados à pull request ou a linhas individuais em arquivos, bem como à pull request geral. Você pode adicionar links a recursos, como arquivos, usando o @ sinal seguido pelo nome do arquivo.

   nota

   O blueprint não será aplicado até que a pull request seja aprovada e mesclada. Para obter mais informações, consulte Analisando uma pull request e Mesclando uma pull request.

6. Na coluna Status, escolha Pull Request pendente para a linha de blueprint PDK - Cloudscape React Website e, em seguida, escolha o link da pull request aberta.

7. Escolha Mesclar, escolha sua estratégia de mesclagem preferida e, em seguida, escolha Mesclar para incorporar as alterações do blueprint aplicado.

   Depois que a pull request é mesclada, uma nova packages/websites/my-website-name pasta é gerada em seu projeto monorepo, que contém todo o código-fonte do seu novo site.

8. No painel de navegação, escolha Blueprints para confirmar se o status do site PDK - Cloudscape React aparece atualizado.

Em seguida, você adicionará o PDK — Infrastructure blueprint para gerar a infraestrutura para implantar seu site na nuvem da AWS.

Etapa 4: gerar a infraestrutura para implantar o aplicativo na nuvem da AWS

O PDK - Infrastructure blueprint configura um pacote contendo todo o seu código CDK para implantar seu site e sua API. Ele também fornece geração de diagramas e conformidade com o pacote de mensagens de prototipagem por padrão.

Para adicionar o PDK - Plano de infraestrutura

1. No painel de navegação do seu projeto monorepo, escolha Blueprints e, em seguida, escolha Adicionar blueprint.

2. Escolha o plano PDK - Infraestrutura e, em seguida, escolha Avançar.

3. Em Configurar blueprint, configure os parâmetros do blueprint:

   • Em Linguagem CDK, escolha a linguagem com a qual você deseja desenvolver sua infraestrutura.

   • No campo de entrada de texto Nome da pilha, insira o nome da CloudFormation pilha gerada para seu blueprint.

     nota

     Anote o nome dessa pilha na próxima etapa, na qual você definirá um DevOps fluxo de trabalho.

   • Escolha o menu suspenso Type Safe APIs e, em seguida, escolha os esquemas de API que você deseja integrar ao site.

   • Escolha o menu suspenso Sites do Cloudscape React TS e, em seguida, escolha os esquemas do site que você deseja implantar em sua infraestrutura (por exemplo, PDK - Site do Cloudscape React).

4. Na guia Alterações no código, revise as alterações propostas. A diferença exibida em uma pull request mostra as alterações em seu projeto no momento em que a pull request foi criada.

5. Quando estiver satisfeito com as alterações propostas que serão feitas quando o blueprint for aplicado, escolha Adicionar blueprint.

   Depois que uma pull request é criada, você pode adicionar comentários. Os comentários podem ser adicionados à pull request ou a linhas individuais em arquivos, bem como à pull request geral. Você pode adicionar links a recursos, como arquivos, usando o @ sinal seguido pelo nome do arquivo.

   nota

   O blueprint não será aplicado até que a pull request seja aprovada e mesclada. Para obter mais informações, consulte Analisando uma pull request e Mesclando uma pull request.

6. Na coluna Status, escolha Pull Request pendente para a linha PDK - Infrastructure blueprint e, em seguida, escolha o link da pull request aberta.

7. Escolha Mesclar, escolha sua estratégia de mesclagem preferida e, em seguida, escolha Mesclar para incorporar as alterações do blueprint aplicado.

   Depois que a pull request é mesclada, uma nova packages/infra pasta é gerada em seu projeto monorepo, que contém a infraestrutura que implantará seu projeto na nuvem da AWS.

8. No painel de navegação, escolha Blueprints para confirmar se o Status do PDK - Infraestrutura aparece Atualizado.

Em seguida, você adicionará o PDK - DevOps blueprint para implantar seu aplicativo.

Etapa 5: configurar um DevOps fluxo de trabalho para implantar seu projeto

O PDK - DevOps blueprint gera os DevOps fluxos de trabalho necessários para criar e implantar seu projeto usando a conta e a função da AWS especificadas na configuração.

Para adicionar o PDK - blueprint DevOps

1. No painel de navegação do seu projeto monorepo, escolha Blueprints e, em seguida, escolha Adicionar blueprint.

2. Escolha o PDK - DevOps blueprint e, em seguida, escolha Avançar.

3. Em Configurar blueprint, configure os parâmetros do blueprint:

   • Escolha Bootstrap CDK no ambiente atual.

   • No campo de entrada de texto Nome da pilha, insira o nome da CloudFormation pilha que você deseja implantar. Isso deve corresponder ao nome da pilha configurado Etapa 4: gerar a infraestrutura para implantar o aplicativo na nuvem da AWS para o PDK - Infrastructure blueprint.

   • Escolha o menu suspenso de conexão da conta da AWS e, em seguida, escolha a conta da AWS que você deseja usar para os recursos. Para ter mais informações, consulte Adicionando um Conta da AWS a um espaço.

   • Escolha o papel a ser usado para implantar seu aplicativo no menu suspenso e, em seguida, escolha o papel do IAM que você deseja usar para implantar seu aplicativo de projeto.

     nota

     Ao criar uma função do IAM, restrinja a SourceArn à atual ProjectID encontrada nas configurações do projeto. Para ter mais informações, consulte Entendendo a função CodeCatalystWorkflowDevelopmentRole-spaceNamede serviço.

   • Escolha o menu suspenso Região e, em seguida, escolha a região na qual você deseja implantar seu projeto monorepo. A implantação só funciona em regiões onde existem os serviços necessários da AWS. Para obter mais informações, consulte Serviços da AWS por região.

4. Na guia Alterações no código, revise as alterações propostas. A diferença exibida em uma pull request mostra as alterações em seu projeto no momento em que a pull request foi criada.

5. Quando estiver satisfeito com as alterações propostas que serão feitas quando o blueprint for aplicado, escolha Adicionar blueprint.

   Depois que uma pull request é criada, você pode adicionar comentários. Os comentários podem ser adicionados à pull request ou a linhas individuais em arquivos, bem como à pull request geral. Você pode adicionar links a recursos, como arquivos, usando o @ sinal seguido pelo nome do arquivo.

   nota

   O blueprint não será aplicado até que a pull request seja aprovada e mesclada. Para obter mais informações, consulte Analisando uma pull request e Mesclando uma pull request.

6. Na coluna Status, escolha Pull Request pendente para a linha PDK - Infrastructure blueprint e, em seguida, escolha o link da pull request aberta.

7. Escolha Mesclar, escolha sua estratégia de mesclagem preferida e, em seguida, escolha Mesclar para incorporar as alterações do blueprint aplicado.

   Depois que a pull request é mesclada, uma nova .codecatalyst/workflows pasta é gerada dentro do seu projeto monorepo.

8. No painel de navegação, escolha Blueprints para confirmar se o Status do PDK - DevOps mostra Atualizado.

nota

O PDK - DevOps blueprint e todas as alterações subsequentes nos blueprints PDK serão significativamente mais lentos a partir de agora, porque os arquivos de bloqueio nos bastidores são gerados para garantir que as compilações e implantações sejam reproduzíveis no futuro. Ele gerará arquivos de bloqueio para todos os pacotes em qualquer um dos idiomas suportados.

Etapa 6: confirme o fluxo de trabalho de lançamento e visualize seu site

Depois de concluir as etapas anteriores, você pode confirmar o fluxo de trabalho de lançamento para garantir que o projeto esteja sendo construído.

Para confirmar o fluxo de trabalho de lançamento e visualizar seu site

1. No painel de navegação do seu projeto monorepo, escolha CI/CD e, em seguida, escolha Fluxos de trabalho.

2. Para o fluxo de trabalho de lançamento, escolha a última execução do fluxo de trabalho para ver os detalhes. Para ter mais informações, consulte Visualizando o status e os detalhes de uma única execução.

3. Depois que a execução do fluxo de trabalho for concluída com êxito, escolha a última ação no fluxo de trabalho (por exemplo, Deploy-B eta-ap-souteast -2) e escolha Variáveis.

   

4. Visualize o site implantado copiando e colando o link encontrado na tabela Variáveis (por exemplo, MyPDKAPI websiteDistributionDomain NameXXXX) em uma nova janela do navegador.

   

   Você precisa de uma conta do Amazon Cognito para fazer login no seu site. Por padrão, o grupo de usuários não está configurado para permitir o autorregistro.

   1. Navegue até o console do AWS Cognito.

   2. Na tabela Grupos de usuários, escolha o nome do grupo de usuários que corresponda ao grupo de usuários criado pelo PDK - DevOps blueprint, que pode ser encontrado na tabela Variáveis (por exemplo, infra calcule betaUserIdentityinfracalcule XXXXX). betaUserIdentity IdentityPoolId Para obter mais informações, consulte Introdução aos grupos de usuários.

      

   3. Selecione Criar usuário.

   4. Configure os parâmetros de informações do usuário:

      • Em Mensagem de convite, escolha Enviar um convite por e-mail.

      • No campo de entrada de texto Nome de usuário, insira um nome de usuário.

      • No campo de entrada de texto do endereço de e-mail, insira um nome de usuário.

      • Em Senha temporária, escolha Gerar uma senha.

   5. Selecione Criar usuário.

   6. Navegue até a conta de e-mail que você inseriu para os parâmetros de informações do usuário e abra um e-mail com uma senha temporária. Anote a senha.

   7. Volte para o site implantado, digite o nome de usuário que você criou e a senha temporária que você recebeu e, em seguida, escolha Entrar.

5. (Opcional) Depois que a execução do fluxo de trabalho for concluída com êxito, você também poderá visualizar o diagrama gerado. Escolha a guia Artefatos em CodeCatalyst, escolha Baixar para a linha Diagrama e abra o (s) arquivo (s) baixado (s).