Tutorial: Criar um projeto no AWS CodeStar com a AWS CLI

Este tutorial mostra como usar a AWS CLI para criar um projeto do AWS CodeStar com o código-fonte de exemplo e um modelo de cadeia de ferramentas de exemplo. O AWS CodeStar provisiona a infraestrutura do AWS e os recursos do IAM especificados em um modelo de cadeia de ferramentas do AWS CloudFormation. O projeto gerencia os recursos da cadeia de ferramentas para criar e implantar o código-fonte.

O AWS CodeStar usa o AWS CloudFormation para compilar e implantar o código de exemplo. Esse código de exemplo cria um serviço da web hospedado no AWS Lambda e que pode ser acessado por meio do Amazon API Gateway.

Pré-requisitos:

• Siga as etapas em Configuração AWS CodeStar.

• Você deve ter criado um bucket de armazenamento do Amazon S3. Neste tutorial, você faz upload do código-fonte de exemplo e do modelo da cadeia de ferramentas para esse local.

nota

A conta da AWS pode ser cobrada pelos custos relacionados a este tutorial, inclusive os serviços da AWS usados pelo AWS CodeStar. Para obter mais informações, consulte Preços do AWS CodeStar.

Etapa 1: Fazer download e analisar o código-fonte de exemplo

Para este tutorial, existe um arquivo zip disponível para download. Ele contém o código-fonte de exemplo de um aplicativo de exemplo Node.js na plataforma de computação Lambda. Quando o código-fonte é colocado no repositório, a pasta e os arquivos são exibidos conforme mostrado:

tests/
app.js
buildspec.yml
index.js
package.json
README.md
template.yml

Os seguintes elementos do projeto são representados no código-fonte de exemplo:

• tests/: testes de unidade configurados para o projeto CodeBuild do projeto. Essa pasta está incluída no código de exemplo, mas não é obrigatória para criar um projeto.

• app.js: código-fonte do aplicativo do projeto.

• buildspec.yml: as instruções de compilação para o estágio de compilação do recurso CodeBuild. Esse arquivo é obrigatório para um modelo de cadeia de ferramentas com um recurso do CodeBuild.

• package.json: as informações de dependências do código-fonte do aplicativo.

• README.md: o arquivo readme do projeto incluído em todos os projetos AWS CodeStar. Esse arquivo está incluído no código de exemplo, mas não é obrigatório para criar um projeto.

• template.yml: o arquivo de modelo da infraestrutura ou o arquivo de modelo SAM incluído em todos os projetos AWS CodeStar. Isso é diferente de template.yml da cadeia de ferramentas que você enviará mais adiante neste tutorial. Esse arquivo está incluído no código de exemplo, mas não é obrigatório para criar um projeto.

Etapa 2: Fazer download do modelo da cadeia de ferramentas de exemplo

O modelo da cadeia de ferramentas de exemplo fornecido para este tutorial cria um repositório (CodeCommit), um pipeline (CodePipeline) e um contêiner de compilações (CodeBuild), além de usar o AWS CloudFormation para implantar o código-fonte em uma plataforma Lambda. Além desses recursos, também há perfis do IAM que você pode usar para definir o escopo das permissões do ambiente do runtime, um bucket do Amazon S3 que o CodePipeline usa para armazenar os artefatos da implantação e uma regra do CloudWatch Events usada para acionar implantações de pipeline ao enviar código para o repositório. Para se alinhar com melhores práticas do IAM da AWS, restrinja as políticas das funções da cadeia de ferramentas definidas neste exemplo.

Faça download e descompacte o modelo do AWS CloudFormation de amostra no formato YAML.

Quando você executar o comando create-project posteriormente no tutorial, este modelo criará os recursos personalizados da cadeia de ferramentas no AWS CloudFormation. Para obter mais informações sobre os recursos criados neste tutorial, consulte os seguintes tópicos no Guia do usuário do AWS CloudFormation:

• O recurso AWS::CodeCommit::Repository do AWS CloudFormation cria um repositório do CodeCommit.

• O recurso do AWS CloudFormation AWS::CodeBuild::Project cria um projeto de compilação do CodeBuild.

• O recurso do AWS CloudFormation AWS::CodeDeploy::Application cria um aplicativo do CodeDeploy.

• O recurso AWS::CodePipeline::Pipeline do AWS CloudFormation cria um pipeline do CodePipeline.

• O recurso do AWS CloudFormation AWS::S3::Bucket cria o bucket de artefatos do seu pipeline.

• O recurso do AWS CloudFormation AWS::S3::BucketPolicy cria a política de bucket de artefatos para o bucket de artefatos do seu pipeline.

• O recurso do AWS CloudFormation AWS::IAM::Role cria a função de trabalhador do CodeBuild IAM que dá permissões AWS CodeStar para gerenciar seu projeto de compilação do CodeBuild.

• O recurso do AWS CloudFormation AWS::IAM::Role cria a função de trabalhador do CodePipeline IAM que dá ao AWS CodeStar permissões para criar seu pipeline.

• O recurso do AWS CloudFormation AWS::IAM::Role cria a função de trabalhador do AWS CloudFormation IAM que dá ao AWS CodeStar permissões para criar sua pilha de recursos.

• O recurso do AWS CloudFormation AWS::IAM::Role cria a função de trabalhador do AWS CloudFormation IAM que dá ao AWS CodeStar permissões para criar sua pilha de recursos.

• O recurso do AWS CloudFormation AWS::IAM::Role cria a função de trabalhador do AWS CloudFormation IAM que dá ao AWS CodeStar permissões para criar sua pilha de recursos.

• O recurso do AWS CloudFormation AWS::Events::Rule cria a regra do CloudWatch Events que monitora seu repositório em busca de eventos push.

• O recurso do AWS CloudFormation AWS::IAM::Role cria o perfil do IAM do CloudWatch Events.

Etapa 3: Testar o modelo da cadeia de ferramentas no AWS CloudFormation

Para fazer upload do modelo da cadeia de ferramentas, você pode testar o modelo da cadeia de ferramentas no AWS CloudFormation e solucionar todos os erros.

1. Salve o modelo atualizado no computador local e abra o console do AWS CloudFormation. Selecione Create Stack (Criar pilha). Seus novos recursos devem ser exibidos na lista.

2. Veja a pilha em busca de eventuais erros de criação.

3. Depois que o teste for concluído, exclua a pilha.

   nota

   Verifique se você excluiu a pilha e todos os recursos criados no AWS CloudFormation. Caso contrário, ao criar o projeto, você poderá encontrar erros para nomes de recursos já em uso.

Etapa 4: Fazer upload do código-fonte e do modelo da cadeia de ferramentas

Para criar um projeto do AWS CodeStar, você deve primeiro empacotar o código-fonte em um arquivo .zip e colocá-lo no Amazon S3. O AWS CodeStar inicializa o repositório com esse conteúdo. Você especifica esse local no arquivo de entrada ao executar o comando para criar o projeto na AWS CLI.

Você também deve fazer upload do arquivo toolchain.yml e colocá-lo no Amazon S3. Você especifica esse local no arquivo de entrada ao executar o comando para criar o projeto na AWS CLI.

Para fazer upload do código-fonte e do modelo da cadeia de ferramentas

1. A estrutura do arquivo de exemplo a seguir mostra os arquivos de origem e o modelo da cadeia de ferramentas prontos para serem compactados e enviados. O código de exemplo inclui o arquivo template.yml. Lembre-se de que esse arquivo é diferente do arquivo toolchain.yml.

   ls
   src toolchain.yml
   
   ls src/
   README.md    app.js        buildspec.yml    index.js    package.json    template.yml    tests

2. Crie o .zip dos arquivos de código-fonte.

   cd src; zip -r "../src.zip" *; cd ../

3. Use o comando cp e inclua os arquivos como parâmetros.

   Os comandos a seguir fazem upload do arquivo .zip e toolchain.yml para o Amazon S3.

   aws s3 cp src.zip s3://MyBucket/src.zip 
   aws s3 cp toolchain.yml s3://MyBucket/toolchain.yml

Para configurar o bucket do Amazon S3 a fim de compartilhar o código-fonte

• Como está armazenando o código-fonte e a cadeia de ferramentas no Amazon S3, você pode usar as políticas de bucket do Amazon S3 e as ACLs de objeto para garantir que outros usuários do IAM ou contas do AWS possam criar projetos com base nas amostras. O AWS CodeStar garante que qualquer usuário que crie um projeto personalizado tenha acesso à cadeia de ferramentas e à fonte que deseja usar.

  Para permitir que qualquer pessoa use a amostra, execute os seguintes comandos:

  aws s3api put-object-acl --bucket MyBucket --key toolchain.yml --acl public-read
  aws s3api put-object-acl --bucket MyBucket --key src.zip --acl public-read

Etapa 5: Criar um projeto no AWS CodeStar

Use estas etapas para criar o projeto.

Importante

Verifique se você configurou a região do AWS preferida na AWS CLI. O projeto é criado na região do AWS configurada na AWS CLI.

1. Execute o comando create-project e inclua o parâmetro --generate-cli-skeleton:

   aws codestar create-project --generate-cli-skeleton

   Os dados formatados JSON aparecem na saída. Copie os dados para um arquivo (por exemplo, input.json) em um local no computador local ou em uma instância na qual a AWS CLI esteja instalada. Modifique os dados copiados da maneira a seguir e salve os resultados. Esse arquivo de entrada é configurado para um projeto chamado MyProject com um nome de bucket myBucket.

   • Certifique-se de fornecer o parâmetro roleArn. Para modelos personalizados, como o exemplo de modelo deste tutorial, é necessário fornecer uma função. Essa função deve ter permissões para criar todos os recursos especificados em Etapa 2: Fazer download do modelo da cadeia de ferramentas de exemplo.

   • Verifique se você forneceu o parâmetro ProjectId em stackParameters. O modelo de exemplo fornecido para este tutorial exige esse parâmetro.

   {
       "name": "MyProject", 
       "id": "myproject", 
       "description": "Sample project created with the CLI", 
       "sourceCode": [
           {
               "source": {
                   "s3": {
                       "bucketName": "MyBucket", 
                       "bucketKey": "src.zip"
                   }
               }, 
               "destination": {
                   "codeCommit": {
                       "name": "myproject"
                   
                   }
               }
           }
       ], 
       "toolchain": {
           "source": {
               "s3": {
                   "bucketName": "MyBucket", 
                   "bucketKey": "toolchain.yml"
               }
           },
           "roleArn": "role_ARN", 
           "stackParameters": {
               "ProjectId": "myproject"
           }
       }
   }

2. Alterne para o diretório que contenha o arquivo que você acabou de salvar e execute o comando create-project novamente. Inclua o parâmetro --cli-input-json.

   aws codestar create-project --cli-input-json file://input.json

3. Se bem-sucedido, dados semelhantes aos seguintes serão exibidos na saída:

   {
       "id": "project-ID",
       "arn": "arn"
   }

   • A saída contém informações sobre o novo projeto:

     • O valor id representa o ID do projeto.

     • O valor arn representa o ARN do projeto.

4. Use o comando describe-project para verificar o status da criação do projeto. Inclua o parâmetro --id.

   aws codestar describe-project --id <project_ID> 

   Dados semelhantes aos seguintes são exibidos na saída:

   {
       "name": "MyProject",
       "id": "myproject",
       "arn": "arn:aws:codestar:us-east-1:account_ID:project/myproject",
       "description": "",
       "createdTimeStamp": 1539700079.472,
       "stackId": "arn:aws:cloudformation:us-east-1:account_ID:stack/awscodestar-myproject/stack-ID",
       "status": {
           "state": "CreateInProgress"
       }
   }

   • A saída contém informações sobre o novo projeto:

     • O valor id representa o ID do projeto exclusivo.

     • O valor state representa o status da criação do projeto, como CreateInProgress ou CreateComplete.

Embora o projeto esteja sendo criado, você pode adicionar membros à equipe ou configurar o acesso ao repositório do projeto na linha de comando ou de seu IDE favorito.