Este é o Guia do Desenvolvedor AWS CDK v2. A CDK v1 mais antiga 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á.
Recursos são o que você configura para usar Serviços da AWS em seus aplicativos. Os recursos são uma característica do AWS CloudFormation. Ao configurar recursos e suas propriedades em um AWS CloudFormation modelo, você pode implantar para AWS CloudFormation provisionar seus recursos. Com o AWS Cloud Development Kit (AWS CDK), você pode configurar recursos por meio de construções. Em seguida, você implanta seu CDK aplicativo, o que envolve sintetizar um AWS CloudFormation modelo e implantá-lo para AWS CloudFormation provisionar seus recursos.
Configurar recursos usando constructos
Conforme descrito emConstructos do AWS CDK, AWS CDK fornece uma rica biblioteca de classes de construções, chamadas de AWS construções, que representam todos os AWS recursos.
Para criar uma instância de um recurso usando seu constructo correspondente, passe o escopo como o primeiro argumento, o ID lógico do constructo e um conjunto de propriedades de configuração (props). Por exemplo, veja como criar uma fila da Amazon com AWS KMS criptografia usando a construção SQS SQS.Queue da Construct Library. AWS
import * as sqs from '@aws-cdk/aws-sqs';
new sqs.Queue(this, 'MyQueue', {
encryption: sqs.QueueEncryption.KMS_MANAGED
});
Alguns props de configuração são opcionais e, em muitos casos, têm valores padrão. Em alguns casos, todos os props são opcionais e o último argumento pode ser totalmente omitido.
Atributos de recursos
A maioria dos recursos na AWS Construct Library expõe atributos, que são resolvidos no momento da implantação pelo AWS CloudFormation. Os atributos são expostos na forma de propriedades nas classes de recursos com o nome do tipo como prefixo. O exemplo a seguir mostra como obter o URL de uma SQS fila da Amazon usando a propriedade queueUrl
(Pythonqueue_url
:).
import * as sqs from '@aws-cdk/aws-sqs';
const queue = new sqs.Queue(this, 'MyQueue');
const url = queue.queueUrl; // => A string representing a deploy-time value
Consulte Tokens e o AWS CDK para obter informações sobre como o AWS CDK codifica atributos de tempo de implantação como cadeias de caracteres.
Fazer referência a recursos
Ao configurar recursos, muitas vezes você precisará referenciar propriedades de outro recurso. Veja os exemplos a seguir:
-
Um recurso do Amazon Elastic Container Service (AmazonECS) exige uma referência ao cluster no qual ele é executado.
-
Uma CloudFront distribuição da Amazon exige uma referência ao bucket do Amazon Simple Storage Service (Amazon S3) contendo o código-fonte.
É possível fazer referência a recursos de qualquer uma das formas a seguir:
-
Ao passar um recurso definido em seu CDK aplicativo, na mesma pilha ou em uma diferente
-
Ao passar um objeto proxy referenciando um recurso definido em sua AWS conta, criado a partir de um identificador exclusivo do recurso (como umARN)
Se a propriedade de um constructo representa um constructo para outro recurso, seu tipo é o tipo de interface de constructo. Por exemplo, a ECS construção da Amazon assume uma propriedade cluster
do tipoecs.ICluster
. Outro exemplo é a construção CloudFront de distribuição que usa uma propriedade sourceBucket
(Python:source_bucket
) do tipo. s3.IBucket
Você pode transmitir diretamente qualquer objeto de recurso do tipo adequado definido no mesmo AWS CDK aplicativo. O exemplo a seguir define um ECS cluster da Amazon e o usa para definir um ECS serviço da Amazon.
const cluster = new ecs.Cluster(this, 'Cluster', { /*...*/ });
const service = new ecs.Ec2Service(this, 'Service', { cluster: cluster });
Como fazer referência a recursos em uma pilha diferente
Você pode se referir aos recursos em uma pilha diferente, desde que estejam definidos no mesma aplicação e no mesmo ambiente AWS . O seguinte padrão é geralmente usado:
-
Armazene uma referência ao constructo como um atributo da pilha que produz o recurso. (Para obter uma referência à pilha do constructo atual, use
Stack.of(this)
.) -
Passe essa referência ao construtor da pilha que consome o recurso como parâmetro ou propriedade. A pilha consumidora então a passa como uma propriedade para qualquer constructo que precise dela.
O exemplo a seguir define uma pilha stack1
. Essa pilha define um bucket do Amazon S3 e armazena uma referência ao constructo do bucket como um atributo da pilha. Em seguida, a aplicação define uma segunda pilha, stack2
, que aceita um bucket na instanciação. O stack2
pode, por exemplo, definir uma tabela AWS Glue que usa o bucket para armazenamento de dados.
const prod = { account: '123456789012', region: 'us-east-1' };
const stack1 = new StackThatProvidesABucket(app, 'Stack1', { env: prod });
// stack2 will take a property { bucket: IBucket }
const stack2 = new StackThatExpectsABucket(app, 'Stack2', {
bucket: stack1.bucket,
env: prod
});
Se AWS CDK determinar que o recurso está no mesmo ambiente, mas em uma pilha diferente, ele sintetiza automaticamente AWS CloudFormation as exportações na pilha de produção e um Fn:: ImportValue na pilha consumidora para transferir essas informações de uma pilha para a outra.
Como resolver os deadlocks de dependência
Fazer referência a um recurso de uma pilha em outra pilha cria uma dependência entre as duas pilhas. Isso garante que eles sejam implantados na ordem correta. Depois que as pilhas são implantadas, essa dependência é concreta. Depois disso, remover o uso do recurso compartilhado da pilha consumidora pode causar uma falha inesperada na implantação. Isso acontece se houver outra dependência entre as duas pilhas que as força a serem implantadas na mesma ordem. Isso também pode acontecer sem dependência se a pilha de produção for simplesmente escolhida pelo CDK kit de ferramentas para ser implantada primeiro. A AWS CloudFormation exportação é removida da pilha de produção porque não é mais necessária, mas o recurso exportado ainda está sendo usado na pilha de consumo porque sua atualização ainda não foi implantada. Portanto, a implantação da pilha do produtor falha.
Para resolver esse impasse, remova o uso do recurso compartilhado da pilha de consumo. (Isso remove a exportação automática da pilha de produção.) Em seguida, adicione manualmente a mesma exportação à pilha de produção usando exatamente o mesmo ID lógico da exportação gerado automaticamente. Remova o uso do recurso compartilhado na pilha de consumo e implante as duas pilhas. Em seguida, remova a exportação manual (e o recurso compartilhado, se não for mais necessário) e implante as duas pilhas novamente. O método exportValue()
da pilha é uma maneira conveniente de criar a exportação manual para essa finalidade. (Veja o exemplo na referência do método vinculado.)
Referenciando recursos em sua conta AWS
Suponha que você queira usar um recurso já disponível na sua AWS conta no seu AWS CDK aplicativo. Isso pode ser um recurso definido por meio do console AWS SDK, diretamente com AWS CloudFormation ou em um AWS CDK aplicativo diferente. Você pode transformar o recurso ARN (ou outro atributo de identificação ou grupo de atributos) em um objeto proxy. O objeto proxy serve como referência ao recurso chamando um método estático de fábrica na classe do recurso.
Quando você cria esse proxy, o recurso externo não se torna parte do seu AWS CDK aplicativo. Portanto, as alterações feitas no proxy em seu AWS CDK aplicativo não afetam o recurso implantado. No entanto, o proxy pode ser passado para qualquer AWS CDK método que exija um recurso desse tipo.
O exemplo a seguir mostra como referenciar um bucket baseado em um bucket existente com o ARN arn:aws:s3: ::amzn-s3-demo-bucket1 e uma Amazon Virtual Private Cloud com base em uma existente com um ID específico. VPC
// Construct a proxy for a bucket by its name (must be same account)
s3.Bucket.fromBucketName(this, 'MyBucket', 'amzn-s3-demo-bucket1');
// Construct a proxy for a bucket by its full ARN (can be another account)
s3.Bucket.fromBucketArn(this, 'MyBucket', 'arn:aws:s3:::amzn-s3-demo-bucket1');
// Construct a proxy for an existing VPC from its attribute(s)
ec2.Vpc.fromVpcAttributes(this, 'MyVpc', {
vpcId: 'vpc-1234567890abcde',
});
Vamos examinar com mais cuidado o método Vpc.fromLookup()
. Como a ec2.Vpc
construção é complexa, talvez você queira selecionar a VPC que será usada com seu CDK aplicativo de várias maneiras. Para resolver isso, a VPC construção tem um método fromLookup
estático (Python:from_lookup
) que permite pesquisar a Amazon desejada VPC consultando sua AWS conta no momento da síntese.
Para usarVpc.fromLookup()
, o sistema que sintetiza a pilha deve ter acesso à conta proprietária da Amazon. VPC Isso ocorre porque o CDK Toolkit consulta a conta para encontrar a Amazon certa no VPC momento da síntese.
Além disso, o Vpc.fromLookup()
funciona somente em pilhas definidas com uma conta e uma região explícitas (consulte Ambientes para o AWS CDK). Se AWS CDK tentar pesquisar uma Amazon a VPC partir de uma pilha independente do ambiente, o CDK Toolkit não sabe qual ambiente consultar para encontrar o. VPC
Você deve fornecer Vpc.fromLookup()
atributos suficientes para identificar exclusivamente um VPC em sua AWS
conta. Por exemplo, só pode haver um padrãoVPC, então basta especificar o VPC como padrão.
ec2.Vpc.fromLookup(this, 'DefaultVpc', {
isDefault: true
});
Você também pode usar a tags
propriedade para consultar VPCs por tag. Você pode adicionar tags à Amazon VPC no momento de sua criação usando AWS CloudFormation ou AWS CDK o. Você pode editar as tags a qualquer momento após a criação usando o AWS Management Console AWS CLI, o ou um AWS SDK. Além de todas as tags que você mesmo adiciona, o adiciona AWS CDK automaticamente as seguintes tags a tudo o VPCs que ele cria.
-
Nome — O nome doVPC.
-
aws-cdk:subnet-name – O nome da sub-rede.
-
aws-cdk:subnet-type – O tipo de sub-rede: pública, privada ou isolada.
ec2.Vpc.fromLookup(this, 'PublicVpc',
{tags: {'aws-cdk:subnet-type': "Public"}});
Os resultados do Vpc.fromLookup()
são armazenados em cache no arquivo cdk.context.json
do projeto. (Consulte Valores de contexto e o AWS CDK.) Confirme esse arquivo com o controle de versão para que seu aplicativo continue se referindo à mesma AmazonVPC. Isso funciona mesmo se você alterar posteriormente os seus atributos de uma VPCs forma que resultaria na seleção VPC de um diferente. Isso é particularmente importante se você estiver implantando a pilha em um ambiente que não tem acesso à AWS conta que a defineVPC, como CDK Pipelines.
Embora você possa usar um recurso externo em qualquer lugar em que usaria um recurso semelhante definido no seu AWS CDK aplicativo, não é possível modificá-lo. Por exemplo, chamar addToResourcePolicy
(Python: add_to_resource_policy
) em um s3.Bucket
externo não faz nada.
Nomes físicos de recursos
Os nomes lógicos dos recursos em AWS CloudFormation são diferentes dos nomes dos recursos que são mostrados AWS Management Console depois de serem implantados pelo AWS CloudFormation. Eles AWS CDK chamam esses nomes finais de nomes físicos.
Por exemplo, AWS CloudFormation pode criar o bucket do Amazon S3 com o ID lógico Stack2MyBucket4DD88B4F
do exemplo anterior com o nome físico. stack2MyBucket4dd88b4f-iuv1rbv9z3to
Você pode especificar um nome físico ao criar construções que representam recursos usando a propriedade <resourceType>
Name. O exemplo a seguir cria um bucket do Amazon S3 com o nome físico MyBucket
.
const bucket = new s3.Bucket(this, 'MyBucket', {
bucketName: 'amzn-s3-demo-bucket',
});
A atribuição de nomes físicos aos recursos tem algumas desvantagens em AWS CloudFormation. Mais importante ainda, qualquer alteração nos recursos implantados que exija a substituição de um recurso, como alterações nas propriedades de um recurso que são imutáveis após a criação, falhará se um recurso tiver um nome físico atribuído. Se você acabar nesse estado, a única solução é excluir a AWS CloudFormation pilha e implantar o AWS CDK aplicativo novamente. Consulte a Documentação do AWS CloudFormation para obter detalhes.
Em alguns casos, como ao criar um AWS CDK aplicativo com referências entre ambientes, nomes físicos são necessários para AWS CDK que o funcione corretamente. Nesses casos, se você não quiser se preocupar em criar um nome físico, pode deixar o AWS CDK nome para você. Para isso, use o valor especial PhysicalName.GENERATE_IF_NEEDED
, da forma a seguir.
const bucket = new s3.Bucket(this, 'MyBucket', {
bucketName: core.PhysicalName.GENERATE_IF_NEEDED,
});
Passando identificadores de recursos exclusivos
Sempre que possível, você deve passar os recursos por referência, conforme descrito na seção anterior. No entanto, há casos em que você não tem outra escolha a não ser se referir a um recurso por meio de um de seus atributos. Alguns casos de uso incluem o seguinte:
-
Quando você está usando AWS CloudFormation recursos de baixo nível.
-
Quando você precisa expor recursos aos componentes de tempo de execução de um AWS CDK aplicativo, como ao se referir às funções do Lambda por meio de variáveis de ambiente.
Esses identificadores estão disponíveis como atributos nos recursos, como os seguintes.
bucket.bucketName lambdaFunc.functionArn securityGroup.groupArn
O exemplo a seguir mostra como passar um nome de bucket gerado para uma AWS Lambda função.
const bucket = new s3.Bucket(this, 'Bucket');
new lambda.Function(this, 'MyLambda', {
// ...
environment: {
BUCKET_NAME: bucket.bucketName,
},
});
Concedendo permissões entre recursos
Construções de alto nível possibilitam a obtenção de permissões com privilégios mínimos, oferecendo requisitos de permissão simples e baseados em intenção para expressar. APIs Por exemplo, muitas construções de L2 oferecem métodos de concessão que você pode usar para conceder permissão a uma entidade (como uma IAM função ou usuário) para trabalhar com o recurso, sem precisar criar instruções de IAM permissão manualmente.
O exemplo a seguir cria as permissões para permitir que a função de execução de uma função do Lambda leia e grave objetos em um determinado bucket do Amazon S3. Se o bucket do Amazon S3 for criptografado com uma AWS KMS chave, esse método também concederá permissões à função de execução da função Lambda para decodificar com a chave.
if (bucket.grantReadWrite(func).success) {
// ...
}
Os métodos de concessão retornam um objeto iam.Grant
. Use o atributo success
do objeto Grant
para determinar se a concessão foi efetivamente aplicada (por exemplo, ela pode não ter sido aplicada em recursos externos). Você também pode usar o método assertSuccess
(Python: assert_success
) do objeto Grant
para garantir que a concessão tenha sido aplicada com sucesso.
Se um método de concessão específico não estiver disponível para o caso de uso específico, você poderá usar um método de concessão genérico para definir uma nova concessão com uma lista específica de ações.
O exemplo a seguir mostra como conceder a uma função do Lambda acesso à ação do Amazon DynamoDB CreateBackup
.
table.grant(func, 'dynamodb:CreateBackup');
Muitos recursos, como as funções do Lambda, exigem que uma função seja assumida ao executar o código. Uma propriedade de configuração permite que você especifique um iam.IRole
. Se nenhuma função for especificada, a função criará automaticamente uma função específica para esse uso. Em seguida, você pode usar métodos de concessão nos recursos para adicionar declarações ao perfil.
Os métodos de concessão são criados usando um nível inferior APIs para lidar com IAM as políticas. As políticas são modeladas como PolicyDocumentobjetos. Adicione declarações diretamente às funções (ou à função anexada de um constructo) usando o método addToRolePolicy
(Python: add_to_role_policy
) ou à política de um recurso (como uma política Bucket
) usando o método addToResourcePolicy
(Python: add_to_resource_policy
).
Métricas de recursos e alarmes
Muitos recursos emitem CloudWatch métricas que podem ser usadas para configurar painéis de monitoramento e alarmes. Constructos de nível superior têm métodos métricos que permitem acessar as métricas sem procurar o nome correto a ser usado.
O exemplo a seguir mostra como definir um alarme quando o número ApproximateNumberOfMessagesNotVisible
de uma SQS fila da Amazon excede 100.
import * as cw from '@aws-cdk/aws-cloudwatch';
import * as sqs from '@aws-cdk/aws-sqs';
import { Duration } from '@aws-cdk/core';
const queue = new sqs.Queue(this, 'MyQueue');
const metric = queue.metricApproximateNumberOfMessagesNotVisible({
label: 'Messages Visible (Approx)',
period: Duration.minutes(5),
// ...
});
metric.createAlarm(this, 'TooManyMessagesAlarm', {
comparisonOperator: cw.ComparisonOperator.GREATER_THAN_THRESHOLD,
threshold: 100,
// ...
});
Se não houver um método para uma métrica específica, você poderá usar o método métrico geral para especificar o nome da métrica manualmente.
As métricas também podem ser adicionadas aos CloudWatch painéis. Consulte CloudWatch.
Tráfego de rede
Em muitos casos, você deve habilitar permissões em uma rede para que uma aplicação funcione, como quando a infraestrutura computacional precisa acessar a camada de persistência. Recursos que estabelecem ou escutam conexões expõem métodos que permitem fluxos de tráfego, incluindo a definição de regras de grupos de segurança ou redeACLs.
IConnectableos recursos têm uma connections
propriedade que é a porta de entrada para a configuração das regras de tráfego de rede.
Você permite que os dados fluam em um determinado caminho de rede usando métodos allow
. O exemplo a seguir permite HTTPS conexões com a web e conexões de entrada do grupo Amazon EC2 Auto fleet2
Scaling.
import * as asg from '@aws-cdk/aws-autoscaling';
import * as ec2 from '@aws-cdk/aws-ec2';
const fleet1: asg.AutoScalingGroup = asg.AutoScalingGroup(/*...*/);
// Allow surfing the (secure) web
fleet1.connections.allowTo(new ec2.Peer.anyIpv4(), new ec2.Port({ fromPort: 443, toPort: 443 }));
const fleet2: asg.AutoScalingGroup = asg.AutoScalingGroup(/*...*/);
fleet1.connections.allowFrom(fleet2, ec2.Port.AllTraffic());
Alguns recursos têm portas padrão associadas a eles. Os exemplos incluem o ouvinte de um balanceador de carga na porta pública e as portas nas quais o mecanismo de banco de dados aceita conexões para instâncias de um banco de dados da AmazonRDS. Nesses casos, você pode aplicar um controle rígido da rede sem precisar especificar manualmente a porta. Para fazer isso, use os métodos allowDefaultPortFrom
e allowToDefaultPort
(Python: allow_default_port_from
, allow_to_default_port
).
O exemplo a seguir mostra como habilitar conexões de qualquer IPV4 endereço e uma conexão de um grupo do Auto Scaling para acessar um banco de dados.
listener.connections.allowDefaultPortFromAnyIpv4('Allow public access');
fleet.connections.allowToDefaultPort(rdsDatabase, 'Fleet can access database');
Processar eventos
Alguns recursos podem atuar como fontes de eventos. Use o método addEventNotification
(Python: add_event_notification
) para registrar um destino de evento para um determinado tipo de evento emitido pelo recurso. Além disso, os métodos addXxxNotification
oferecem uma maneira simples de registrar um manipulador para tipos de eventos comuns.
O exemplo a seguir mostra como acionar uma função do Lambda quando um objeto é adicionado a um bucket do Amazon S3.
import * as s3nots from '@aws-cdk/aws-s3-notifications';
const handler = new lambda.Function(this, 'Handler', { /*…*/ });
const bucket = new s3.Bucket(this, 'Bucket');
bucket.addObjectCreatedNotification(new s3nots.LambdaDestination(handler));
Políticas de remoção
Recursos que mantêm dados persistentes, como bancos de dados, buckets do Amazon S3 e ECR registros da Amazon, têm uma política de remoção. A política de remoção indica se objetos persistentes devem ser excluídos quando a pilha AWS CDK
que os contém for destruída. Os valores que especificam a política de remoção estão disponíveis por meio da RemovalPolicy
enumeração no módulo. AWS CDK core
nota
Recursos além daqueles que armazenam dados de forma persistente também podem ter um removalPolicy
que é usado para uma finalidade diferente. Por exemplo, uma versão da função do Lambda usa um atributo removalPolicy
para determinar se uma determinada versão é retida quando uma nova versão é implantada. Eles têm significados e padrões diferentes em comparação com a política de remoção em um bucket do Amazon S3 ou uma tabela do DynamoDB.
Valor | Significado |
---|---|
|
Manter o conteúdo do recurso ao destruir a pilha (padrão). O recurso fica órfão da pilha e deve ser excluído manualmente. Se você tentar reimplantar a pilha enquanto o recurso ainda existe, você receberá uma mensagem de erro devido a um conflito de nomes. |
|
O recurso será destruído junto com a pilha. |
AWS CloudFormation não remove buckets do Amazon S3 que contêm arquivos, mesmo que sua política de remoção esteja definida como. DESTROY
Tentar fazer isso é um AWS CloudFormation erro. Para AWS CDK excluir todos os arquivos do bucket antes de destruí-lo, defina a autoDeleteObjects
propriedade do bucket comotrue
.
Veja a seguir um exemplo de criação de um bucket do Amazon S3 com RemovalPolicy
de DESTROY
e autoDeleteOjbects
definido como true
.
import * as cdk from '@aws-cdk/core';
import * as s3 from '@aws-cdk/aws-s3';
export class CdkTestStack extends cdk.Stack {
constructor(scope: cdk.Construct, id: string, props?: cdk.StackProps) {
super(scope, id, props);
const bucket = new s3.Bucket(this, 'Bucket', {
removalPolicy: cdk.RemovalPolicy.DESTROY,
autoDeleteObjects: true
});
}
}
Você também pode aplicar uma política de remoção diretamente ao AWS CloudFormation recurso subjacente por meio do applyRemovalPolicy()
método. Esse método está disponível em alguns recursos com estado que não têm uma propriedade removalPolicy
nas propriedades do recurso L2. Os exemplos incluem:
-
AWS CloudFormation pilhas
-
Grupos de usuários do Amazon Cognito
-
Instâncias de banco de dados do Amazon DocumentDB
-
EC2Volumes da Amazon
-
OpenSearch Domínios do Amazon Service
-
Sistemas de FSx arquivos da Amazon
-
SQSFilas da Amazon
const resource = bucket.node.findChild('Resource') as cdk.CfnResource;
resource.applyRemovalPolicy(cdk.RemovalPolicy.DESTROY);
nota
O “ AWS CDK s” RemovalPolicy
se traduz em AWS CloudFormation“DeletionPolicy
s”. No entanto, o padrão AWS CDK é reter os dados, o que é o oposto do AWS CloudFormation padrão.