Este é o Guia do desenvolvedor do AWS CDK v2. O CDK v1 antigo entrou em manutenção em 1º de junho de 2022 e encerrou o suporte em 1º de junho de 2023.

As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

# `cdk deploy`
<a name="ref-cli-cmd-deploy"></a>

Implantação de uma ou mais pilhas do AWS CDK em seu ambiente da AWS.

Durante a implantação, a CLI do CDK produzirá indicadores de andamento, semelhantes aos que podem ser observados no console do AWS CloudFormation.

Se o ambiente AWS não tiver sofrido bootstrapping, somente pilhas sem ativos e com modelos sintetizados abaixo de 51.200 bytes serão implantadas com sucesso.

## Uso
<a name="ref-cli-cmd-deploy-usage"></a>

```
$ cdk deploy <arguments> <options>
```

## Argumentos
<a name="ref-cli-cmd-deploy-args"></a><a name="ref-cli-cmd-deploy-args-stack-name"></a>

 **ID da pilha CDK**   
O ID de constructo da pilha CDK da sua aplicação a ser implantado.  
 *Tipo:* string  
 *Obrigatório*: não

## Opções
<a name="ref-cli-cmd-deploy-options"></a>

Para obter uma lista das opções globais que funcionam com todos os comandos da CLI do CDK, consulte [Opções globais](ref-cli-cmd.md#ref-cli-cmd-options).<a name="ref-cli-cmd-deploy-options-all"></a>

 `--all <BOOLEAN>`   
Implantar todas as pilhas em sua aplicação CDK.  
 *Valor padrão*: `false` <a name="ref-cli-cmd-deploy-options-asset-parallelism"></a>

 `--asset-parallelism <BOOLEAN>`   
Especificar se deseja compilar e publicar ativos em paralelo.<a name="ref-cli-cmd-deploy-options-asset-prebuild"></a>

 `--asset-prebuild <BOOLEAN>`   
Especificar se deseja compilar todos os ativos antes de implantar a primeira pilha. Essa opção é útil para compilações do Docker com falha.  
 *Valor padrão*: `true` <a name="ref-cli-cmd-deploy-options-build-exclude"></a>

 `--build-exclude, -E <ARRAY>`   
Não recompile o ativo com o ID fornecido.  
Esta opção pode ser especificada várias vezes em um único comando.  
 *Valor padrão*: `[]` <a name="ref-cli-cmd-deploy-options-change-set-name"></a>

 `--change-set-name <STRING>`   
O nome do conjunto de alterações do AWS CloudFormation a ser criado.  
Essa opção não é compatível com o `--method='direct'`.<a name="ref-cli-cmd-deploy-options-concurrency"></a>

 `--concurrency <NUMBER>`   
Implante várias pilhas em paralelo enquanto contabiliza as dependências entre pilhas. Use essa opção para acelerar as implantações. Você ainda deve considerar o AWS CloudFormation e outras limitações de taxa da conta da AWS.  
Forneça um número para especificar o número máximo de implantações simultâneas (se a dependência permitir) a serem executadas.  
 *Valor padrão*: `1` <a name="ref-cli-cmd-deploy-options-exclusively"></a>

 `--exclusively, -e <BOOLEAN>`   
Implante somente as pilhas solicitadas e não inclua dependências.<a name="ref-cli-cmd-deploy-options-force"></a>

 `--force, -f <BOOLEAN>`   
Quando você implanta para atualizar uma pilha existente, a CLI do CDK compara o modelo e as tags da pilha implantada com a pilha prestes a ser implantada. Se nenhuma alteração for detectada, a CLI do CDK pulará a implantação.  
Para ignorar esse comportamento e sempre implantar pilhas, mesmo que nenhuma alteração seja detectada, use essa opção.  
 *Valor padrão*: `false` <a name="ref-cli-cmd-deploy-options-help"></a>

 `--help, -h <BOOLEAN>`   
Mostrar as informações de referência do comando `cdk deploy`.<a name="ref-cli-cmd-deploy-options-hotswap"></a>

 `--hotswap <BOOLEAN>`   
Implantações de hotswap para um desenvolvimento mais rápido. Essa opção tenta realizar uma implantação de hotswap mais rápida, se possível. Por exemplo, se você modificar o código de uma função do Lambda em sua aplicação do CDK, a CLI do CDK atualizará o recurso diretamente por meio de APIs de serviço em vez de realizar uma implantação do CloudFormation.  
Se a CLI do CDK detectar alterações que não ofereçam suporte ao hotswapping, essas alterações serão ignoradas e uma mensagem será exibida. Se você preferir realizar uma implantação completa do CloudFormation como alternativa, use `--hotswap-fallback` em vez disso.  
A CLI do CDK usa suas credenciais da AWS atuais para realizar as chamadas de API. Ele não assume os perfis de sua pilha de bootstrapping, mesmo se o sinalizador de atributo `@aws-cdk/core:newStyleStackSynthesis` estiver definido como `true`. Esses perfis não têm as permissões necessárias para atualizar os recursos da AWS diretamente, sem usar o CloudFormation. Por isso, certifique-se de que suas credenciais sejam da mesma conta da AWS que as pilhas nas quais você está realizando implantações de hotswap e que elas tenham as permissões de IAM necessárias para atualizar os recursos.  
No momento, o Hotswapping é compatível com as seguintes alterações:  
+ Ativos de código (incluindo imagens do Docker e código embutido), alterações de tags e alterações de configuração (somente descrição e variáveis de ambiente são suportadas) das funções do Lambda.
+ Versões do Lambda e alterações de alias.
+ Alterações na definição de máquinas de estado do AWS Step Functions.
+ Alterações de ativos de contêineres dos serviços do Amazon ECS.
+ Alterações de ativos do site nas implantações de buckets do Amazon S3.
+ Alterações na origem e no ambiente de projetos do AWS CodeBuild.
+ Alterações no modelo de mapeamento de VTL para resolvedores e funções do AWS AppSync.
+ Alterações no esquema das APIs AWS AppSync GraphQL.
O uso de determinadas funções intrínsecas do CloudFormation é suportado como parte de uma implantação com hotswaps. Isso inclui:  
+  `Ref` 
+  `Fn::GetAtt` – Suportado apenas parcialmente. Consulte [essa implementação](https://github.com/aws/aws-cdk/blob/main/packages/aws-cdk/lib/api/evaluate-cloudformation-template.ts#L477-L492) para obter recursos e atributos compatíveis.
+  `Fn::ImportValue` 
+  `Fn::Join` 
+  `Fn::Select` 
+  `Fn::Split` 
+  `Fn::Sub` 
Essa opção também é compatível com pilhas aninhadas.  
+ Essa opção introduz deliberadamente o desvio nas pilhas do CloudFormation para acelerar as implantações. Por isso, use-a apenas para fins de desenvolvimento. Não use esta opção para suas implantações de produção.
+ Essa opção é considerada experimental e pode ter alterações significativas no futuro.
+ Os padrões para determinados parâmetros podem ser diferentes com o parâmetro hotswap. Por exemplo, a porcentagem íntegra mínima de um serviço Amazon ECS será atualmente definida como `0`. Revise a fonte adequadamente se isso ocorrer.
 *Valor padrão*: `false` <a name="ref-cli-cmd-deploy-options-hotswap-fallback"></a>

 `--hotswap-fallback <BOOLEAN>`   
Essa opção é semelhante a `--hotswap`. A diferença é que `--hotswap-fallback` recorrerá à execução de uma implantação completa do CloudFormation se for detectada uma alteração que exija isso.  
Para obter mais informações sobre essa opção, consulte `--hotswap`.  
 *Valor padrão*: `false` <a name="ref-cli-cmd-deploy-options-ignore-no-stacks"></a>

 `--ignore-no-stacks <BOOLEAN>`   
Execute uma implantação mesmo que sua aplicação CDK não contenha nenhuma pilha.  
Essa opção é útil no seguinte cenário: É possível ter uma aplicação com vários ambientes, como `dev` e `prod`. Ao iniciar o desenvolvimento, sua aplicação de produção pode não ter nenhum recurso ou os recursos podem ser comentados. Isso resultará em um erro de implantação com uma mensagem informando que a aplicação não tem pilhas. Use `--ignore-no-stacks` para ignorar esse erro.  
 *Valor padrão*: `false` <a name="ref-cli-cmd-deploy-options-import-existing-resources"></a>

 `--import-existing-resources <BOOLEAN>`   
Importe recursos existentes e não gerenciados do AWS CloudFormation da sua conta da AWS.  
Quando você usa essa opção, os recursos do seu modelo sintetizado do AWS CloudFormation com o mesmo nome personalizado dos recursos não gerenciados existentes na mesma conta serão importados para sua pilha.  
É possível usar essa opção para importar recursos existentes para pilhas novas ou existentes.  
É possível importar recursos existentes e implantar novos recursos no mesmo comando `cdk deploy`.  
Para saber mais sobre nomes personalizados, consulte [Tipo de nome](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-name.html) no *Guia do usuário do AWS CloudFormation*.  
Para saber mais sobre o parâmetro `ImportExistingResources` do CloudFormation, consulte [O AWS CloudFormation simplifica a importação de recursos com um novo parâmetro para ChangeSets](https://aws.amazon.com/about-aws/whats-new/2023/11/aws-cloudformation-import-parameter-changesets/).  
Para obter mais informações sobre como usar essa opção, consulte [Importação de recursos existentes](https://github.com/aws/aws-cdk-cli/tree/main/packages/aws-cdk#import-existing-resources) no *repositório aws-cdk-cli do GitHub*.<a name="ref-cli-cmd-deploy-options-logs"></a>

 `--logs <BOOLEAN>`   
Mostre o log do Amazon CloudWatch na saída padrão (`stdout`) para todos os eventos de todos os recursos nas pilhas selecionadas.  
Essa opção é compatível apenas com o `--watch`.  
 *Valor padrão*: `true` <a name="ref-cli-cmd-deploy-options-method"></a>

 `--method, -m <STRING>`   
Configure o método para realizar uma implantação.  
+  `change-set` – Método padrão. A CLI do CDK cria um conjunto de alterações do CloudFormation com as alterações que serão implantadas e, em seguida, executa a implantação.
+  `direct` – Não crie um conjunto de alterações. Em vez disso, aplique a alteração imediatamente. Normalmente, isso é mais rápido do que criar um conjunto de alterações, mas você perde os detalhes do andamento da implantação na saída da CLI.
+  `prepare-change-set` – Crie um conjunto de alterações, mas não realize a implantação. Isso é útil se você tiver ferramentas externas que inspecionarão o conjunto de alterações ou se você tiver um processo de aprovação para conjuntos de alterações.
 *Valores válidos*: `change-set`, `direct`, `prepare-change-set`   
 *Valor padrão*: `change-set` <a name="ref-cli-cmd-deploy-options-notification-arns"></a>

 `--notification-arns <ARRAY>`   
Os ARNs dos tópicos do Amazon SNS que o CloudFormation notificará sobre eventos relacionados à pilha.<a name="ref-cli-cmd-deploy-options-outputs-file"></a>

 `--outputs-file, -O <STRING>`   
O caminho para onde as saídas da pilha das implantações são gravadas.  
Depois da implantação, as saídas da pilha serão gravadas no arquivo de saída especificado no formato JSON.  
É possível configurar essa opção no arquivo `cdk.json` do projeto ou no `~/.cdk.json` em sua máquina de desenvolvimento local:  

```
{
   "app": "npx ts-node bin/myproject.ts",
   // ...
   "outputsFile": "outputs.json"
}
```
Se várias pilhas forem implantadas, as saídas serão gravadas no mesmo arquivo de saída, organizadas por chaves que representam o nome da pilha.<a name="ref-cli-cmd-deploy-options-parameters"></a>

 `--parameters <ARRAY>`   
Passe parâmetros adicionais para o CloudFormation durante a implantação.  
Esta opção aceita uma matriz no formato a seguir: `STACK:KEY=VALUE`.  
+  `STACK` – O nome da pilha ao qual associar o parâmetro.
+  `KEY` – O nome do parâmetro da sua pilha.
+  `VALUE` – O valor a ser repassado na implantação.
Se o nome da pilha não for fornecido, ou se `*` for fornecido como o nome da pilha, os parâmetros serão aplicados a todas as pilhas que estão sendo implantadas. Se uma pilha não usar o parâmetro, a implantação falhará.  
Os parâmetros não se propagam para pilhas aninhadas. Para passar parâmetros para pilhas aninhadas, use o constructo ` [NestedStack](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.NestedStack.html) `.  
 *Valor padrão*: `{}` <a name="ref-cli-cmd-deploy-options-previous-parameters"></a>

 `--previous-parameters <BOOLEAN>`   
Use valores anteriores para os parâmetros existentes.  
Quando essa opção é definida como `false`, você deve especificar todos os parâmetros em cada implantação.  
 *Valor padrão*: `true` <a name="ref-cli-cmd-deploy-options-progress"></a>

 `--progress <STRING>`   
Configure como a CLI do CDK exibe o andamento da implantação.  
+  `bar` – Exibir os eventos de implantação da pilha como uma barra de andamento, com os eventos do recurso que está sendo implantado no momento.
+  `events` – Fornecer um histórico completo, incluindo todos os eventos do CloudFormation.
Você também pode configurar essa opção no arquivo `cdk.json` do projeto ou em `~/.cdk.json` na sua máquina de desenvolvimento local:  

```
{
   "progress": "events"
}
```
 *Valores válidos*: `bar`, `events`   
 *Valor padrão*: `bar` <a name="ref-cli-cmd-deploy-options-require-approval"></a>

 `--require-approval <STRING>`   
Especifique quais alterações sensíveis à segurança exigem aprovação manual.  
+  `any-change` – É necessária aprovação manual para qualquer alteração na pilha.
+  `broadening` – É necessária aprovação manual se as alterações envolverem uma ampliação das permissões ou das regras do grupo de segurança.
+  `never` – A aprovação não é necessária.
 *Valores válidos*: `any-change`, `broadening`, `never`   
 *Valor padrão*: `broadening` <a name="ref-cli-cmd-deploy-options-rollback"></a>

 `--rollback` \$1 `--no-rollback`, `-R`   
Durante a implantação, se um recurso não for criado ou atualizado, a implantação voltará ao estado estável mais recente antes que a CLI do CDK retorne. Todas as alterações feitas até esse ponto serão desfeitas. Os recursos criados serão excluídos e as atualizações feitas serão revertidas.  
Especifique `--no-rollback` para desativar esse comportamento. Se um recurso não for criado ou atualizado, a CLI do CDK manterá as alterações feitas até aquele momento e retornará. Isso deixará sua implantação em um estado de falha e pausa. A partir daqui, você pode atualizar seu código e tentar a implantação novamente. Isso pode ser útil em ambientes de desenvolvimento em que você está iterando rapidamente.  
Se uma implantação realizada com o `--no-rollback` falhar e você decidir reverter a implantação, poderá usar o comando `cdk rollback`. Para obter mais informações, consulte [cdk rollback](ref-cli-cmd-rollback.md).  
Com o `--no-rollback`, implantações que causam substituições de recursos sempre falharão. Você só pode usar esse valor de opção para implantações que atualizam ou criam novos recursos.
 *Valor padrão*: `--rollback` <a name="ref-cli-cmd-deploy-options-toolkit-stack-name"></a>

 `--toolkit-stack-name <STRING>`   
O nome da pilha existente do Kit de Ferramentas CDK.  
Por padrão, o `cdk bootstrap` implanta uma pilha chamada `CDKToolkit` no ambiente AWS especificado. Use essa opção para fornecer um nome diferente para sua pilha de bootstrapping.  
A CLI do CDK usa esse valor para verificar a versão da pilha de bootstrapping.<a name="ref-cli-cmd-deploy-options-watch"></a>

 `--watch <BOOLEAN>`   
Observe continuamente os arquivos de projeto do CDK e implante automaticamente as pilhas especificadas quando as alterações forem detectadas.  
Essa opção implica `--hotswap` por padrão.  
Essa opção tem um comando da CLI do CDK equivalente. Para obter mais informações, consulte [cdk watch](ref-cli-cmd-watch.md).

## Exemplos
<a name="ref-cli-cmd-deploy-examples"></a>

### Implante a pilha chamada MyStackName
<a name="ref-cli-cmd-deploy-examples-1"></a>

```
$ cdk deploy MyStackName --app='node bin/main.js'
```

### Implante várias pilhas em uma aplicação
<a name="ref-cli-cmd-deploy-examples-2"></a>

Use `cdk list` para listar suas pilhas:

```
$ cdk list
CdkHelloWorldStack
CdkStack2
CdkStack3
```

Para implantar todas as pilhas, use a opção `--all`:

```
$ cdk deploy --all
```

Para escolher quais pilhas implantar, forneça os nomes das pilhas como argumentos:

```
$ cdk deploy CdkHelloWorldStack CdkStack3
```

### Implantar pilhas de pipeline
<a name="ref-cli-cmd-deploy-examples-3"></a>

Use `cdk list` para mostrar os nomes das pilhas como caminhos, mostrando onde elas estão na hierarquia do pipeline:

```
$ cdk list
PipelineStack
PiplelineStack/Prod
PipelineStack/Prod/MyService
```

Use a `--all` opção ou o curinga `*` para implantar todas as pilhas. Se você tiver uma hierarquia de pilhas, conforme descrito acima, `--all` e `*` só combinarão as pilhas no nível superior. Para combinar todas as pilhas na hierarquia, use `**`.

É possível combinar esses padrões. O seguinte implementa todas as pilhas no estágio `Prod`:

```
$ cdk deploy PipelineStack/Prod/**
```

### Passe os parâmetros na implantação
<a name="ref-cli-cmd-deploy-examples-4"></a>

Defina os parâmetros em sua pilha do CDK. Veja a seguir um exemplo de criação de um parâmetro chamado `TopicNameParam` para um tópico do Amazon SNS:

```
new sns.Topic(this, 'TopicParameter', {
    topicName: new cdk.CfnParameter(this, 'TopicNameParam').value.toString()
});
```

Para fornecer um valor de parâmetro de `parameterized`, execute o seguinte:

```
$ cdk deploy --parameters "MyStackName:TopicNameParam=parameterized"
```

É possível substituir os valores dos parâmetros usando a opção `--force`. Veja a seguir um exemplo de como substituir o nome do tópico de uma implantação anterior:

```
$ cdk deploy --parameters "MyStackName:TopicNameParam=parameterName" --force
```

### Grave as saídas da pilha em um arquivo após a implantação
<a name="ref-cli-cmd-deploy-examples-5"></a>

Defina as saídas em seu arquivo de pilha CDK. Veja a seguir um exemplo que cria uma saída para um ARN de função:

```
const fn = new lambda.Function(this, "fn", {
  handler: "index.handler",
  code: lambda.Code.fromInline(`exports.handler = \${handler.toString()}`),
  runtime: lambda.Runtime.NODEJS_LATEST
});

new cdk.CfnOutput(this, 'FunctionArn', {
  value: fn.functionArn,
});
```

Implantar a pilha e gravar as saídas em `outputs.json`:

```
$ cdk deploy --outputs-file outputs.json
```

Veja a seguir um exemplo do `outputs.json` depois da implantação:

```
{
  "MyStack": {
    "FunctionArn": "arn:aws:lambda:us-east-1:123456789012:function:MyStack-fn5FF616E3-G632ITHSP5HK"
  }
}
```

Neste exemplo, a chave `FunctionArn` corresponde ao ID lógico da instância `CfnOutput`.

Veja a seguir um exemplo do `outputs.json` depois da implantação de várias pilhas:

```
{
  "MyStack": {
    "FunctionArn": "arn:aws:lambda:us-east-1:123456789012:function:MyStack-fn5FF616E3-G632ITHSP5HK"
  },
  "AnotherStack": {
    "VPCId": "vpc-z0mg270fee16693f"
  }
}
```

### Modificar o método de implantação
<a name="ref-cli-cmd-deploy-examples-6"></a>

Para implantar com mais rapidez, sem usar conjuntos de alterações, use `--method='direct'`:

```
$ cdk deploy --method='direct'
```

Para criar um conjunto de alterações, mas não implantar, use `--method='prepare-change-set'`. Por padrão, um conjunto de alterações chamado `cdk-deploy-change-set` será criado. Se existir um conjunto de alterações anterior com esse nome, ele será substituído. Se nenhuma alteração for detectada, um conjunto de alterações vazio ainda será criado.

Você também pode nomear seu conjunto de alterações. Veja um exemplo a seguir:

```
$ cdk deploy --method='prepare-change-set' --change-set-name='MyChangeSetName'
```