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á.

AWS Validação de CDK no momento da síntese

Validação no momento da síntese

Seu aplicativo AWS CDK gera uma descrição da infraestrutura no momento da síntese na forma de CloudFormation modelos. Esses modelos são validados imediatamente após a síntese. O AWS CDK vem com um conjunto integrado de regras de validação, que você pode estender com outras ferramentas de CDK-specific validação, como CDK Nag, ou qualquer ferramenta de validação de políticas que sua organização já esteja usando, como AWS CloudFormation Guard ou OPA. Se houver alguma violação, a síntese falhará e um relatório será impresso no console. Usando a validação off-line de seus modelos sintetizados, você pode descobrir e corrigir possíveis problemas com sua infraestrutura com antecedência. Você usaria a validação para encontrar problemas que levariam a falhas de implantação, configurações incorretas comuns ou falha na conformidade com os padrões da empresa.

O que é e o que não é validação

A validação realizada pelo AWS CDK no momento da síntese é a melhor validação para melhorar a experiência do desenvolvedor; por si só, não é um mecanismo completo de conformidade com os padrões. Ele valida os modelos gerados normalmente por um aplicativo CDK, mas não pode afetar as ações que ocorrem fora da síntese. Por exemplo, ações realizadas diretamente no console ou por meio de APIs de serviço. Além disso, como os aplicativos CDK são escritos em uma linguagem de programação de uso geral, determinados desenvolvedores podem ignorar o mecanismo de validação, se quiserem. É por isso que a validação de CDK é um mecanismo de mudança para a esquerda para validar antecipadamente e deve ser usada em combinação com outro mecanismo para validar os conjuntos de regras desejados, como ganchos ou Config.AWS CloudFormation AWS

Para desenvolvedor de aplicações

Adicionando plug-ins de validação

A validação é realizada por plug-ins de validação. Um plug-in padrão que usa um conjunto de regras abrangente para recursos da AWS é adicionado automaticamente ao seu aplicativo, com base em @ aws/cloudformation -validate. Se você quiser adicionar outros plug-ins ao seu aplicativo, use a Validations classe:

import { Validations } from 'aws-cdk-lib';
import { CfnGuardValidator } from '@cdklabs/cdk-validator-cfnguard';

const app = new App();

// Add a validation plugin to the entire app
Validations.of(app).addPlugins(new CfnGuardValidator());

// Or add to a particular stage
const prodStage = new Stage(app, 'ProdStage');
Validations.of(prodStage).addPlugins(new CfnGuardValidator());

Imediatamente após a síntese, todos os plug-ins registrados dessa forma serão invocados para validar todos os modelos gerados no escopo que você definiu. Em particular, se você registrar os modelos no objeto App, todos os modelos estarão sujeitos à validação.

Relatório de validação

Quando você sintetiza o aplicativo AWS CDK, os plug-ins do validador serão chamados e os resultados serão impressos. Um exemplo de relatório está sendo exibido abaixo.

lib/my-custom-l3-construct.ts:10:5
ERROR [CT.S3.PR.1]: Require an Amazon S3 bucket to have block public access settings configured (cdk-validator-cfnguard)
   MyStack/MyCustomL3Construct/Bucket/Resource (MyCustomL3ConstructBucket8C61BCA7) constructs.Construct
   Suggested fix: [FIX]: The parameters 'BlockPublicAcls', 'BlockPublicPolicy', 'IgnorePublicAcls', 'RestrictPublicBuckets' must be set to true under the bucket-level 'PublicAccessBlockConfiguration'.
   Acknowledge with 'cdk-validator-cfnguard::s3_bucket_level_public_access_prohibited_check'

lib/my-custom-l3-construct.ts:10:5
ERROR [CT.S3.PR.10]: Require an Amazon S3 bucket to have server-side encryption configured using an AWS KMS key (cdk-validator-cfnguard)
   MyStack/MyCustomL3Construct/Bucket/Resource (MyCustomL3ConstructBucket8C61BCA7) constructs.Construct
   Suggested fix: [FIX]: Set an encryption rule in 'BucketEncryption.ServerSideEncryptionConfiguration' with a 'ServerSideEncryptionByDefault.SSEAlgorithm' configuration of 'aws:kms' or 'aws:kms:dsse'
   Acknowledge with 'cdk-validator-cfnguard::s3_bucket_default_encryption_kms_check'

...

Por padrão, o relatório será impresso em um formato legível por humanos. Se você quiser um relatório no formato JSON, habilite-o usando @aws-cdk/core:validationReportJson via a CLI ou passando-o diretamente para a aplicação:

const app = new App({
  context: { '@aws-cdk/core:validationReportJson': true },
});

Como alternativa, você pode definir esse par de chave-valor de contexto usando os cdk.context.json arquivos cdk.json ou no diretório do seu projeto (consulte Valores de contexto e o AWS CDK).

Se você escolher o formato JSON, o AWS CDK imprimirá o relatório de validação da política em um arquivo chamado policy-validation-report.json no diretório de montagem na nuvem. Para o formato padrão legível por humanos, o relatório será impresso na saída padrão.

Reconhecendo os avisos

Se você avaliou um aviso ou erro e considerou que ele não se aplica a você, você pode suprimi-lo usando o acknowledge método. A supressão é baseada no escopo e se aplica a todas as construções sob o escopo determinado.

import { Validations } from 'aws-cdk-lib';

Validations.of(myConstruct).acknowledge({
  id: 'PluginName::MyWarningId',
  reason: 'This is acceptable for our use case',
});

O id usa um :: delimitador para separar o prefixo da fonte de validação do nome da regra (por exemplo, ou). Construct-Annotations:: AwsSolutions-S1::

AWS CloudFormation Plugin de proteção

O uso do CfnGuardValidatorplug-in permite que você use o AWS CloudFormation Guard para realizar validações de políticas. O plug-in CfnGuardValidator vem com um conjunto selecionado de controles proativos do AWS Control Tower incorporados. O conjunto atual de regras pode ser encontrado na documentação do projeto. Conforme mencionado em Validação de políticas no momento da síntese, recomendamos que as organizações configurem um método de validação mais confiável usando AWS CloudFormation ganchos.

Para os clientes do AWS Control Tower, esses mesmos controles proativos podem ser implantados em toda a sua organização. Quando você ativa os controles proativos da AWS Control Tower em seu ambiente de AWS Control Tower, os controles podem interromper a implantação de recursos não compatíveis implantados via. AWS CloudFormation Para obter mais informações sobre controles proativos gerenciados e como eles funcionam, consulte a documentação do AWS Control Tower.

Esses controles agrupados do AWS CDK e os controles proativos gerenciados da AWS Control Tower são melhor usados juntos. Nesse cenário, você pode configurar esse plug-in de validação com os mesmos controles proativos que estão ativos em seu ambiente de nuvem da AWS Control Tower. Em seguida, você pode rapidamente ter certeza de que seu aplicativo AWS CDK passará pelos controles da AWS Control Tower executando cdk synth localmente.

AWS Plug-in CDK Nag

Você pode usar o CDK Nag para verificar sua infraestrutura em relação a vários padrões, como HIPAA, PCI DSS e assim por diante. A versão 3.x do cdk-nag se integra ao mecanismo de validação padronizado no CDK.

Para autores de construções: adicionando avisos e erros diretamente

A Validations classe também fornece métodos para adicionar avisos e erros personalizados diretamente às suas construções. Você pode usar esse mecanismo para relatar configurações incorretas diretamente em sua construção sem precisar implementar um plug-in de validação. As validações e erros que você adicionar dessa forma serão relatados junto com as violações encontradas pelos plug-ins de validação.

import { Validations } from 'aws-cdk-lib';

const bucket = new s3.Bucket(this, 'MyBucket');

// Add a warning
Validations.of(bucket).addWarning('MyWarningId', 'This bucket does not have versioning enabled');

// Add an error (will cause synthesis to fail)
Validations.of(bucket).addError('MyErrorId', 'This bucket must have encryption enabled');

Para autores de plugins

A estrutura principal do AWS CDK é responsável por registrar e invocar plug-ins e, em seguida, exibir o relatório de validação formatado. A responsabilidade do plug-in é atuar como a camada de tradução entre a estrutura do AWS CDK e uma ferramenta externa de validação de políticas que seu plug-in pode, por exemplo, usar. Um plug-in pode ser criado em qualquer idioma suportado pelo AWS CDK. Se você estiver criando um plug-in que pode ser consumido por vários idiomas, é recomendável criar o plug-in TypeScript para poder usar o JSII para publicar o plug-in em cada linguagem AWS CDK.

Criar plug-ins

O protocolo de comunicação entre o módulo principal do AWS CDK e sua ferramenta de política é definido pela IPolicyValidationPlugin interface. Para criar um novo plug-in, você deve escrever uma classe que implemente essa interface. Há duas coisas que você precisa implementar: o nome do plug-in (substituindo a propriedade name) e o método validate().

A estrutura chamará validate(), passando um objeto IPolicyValidationContext. A localização dos modelos a serem validados é fornecida pelo templatePaths. O plug-in deve retornar uma instância de PolicyValidationPluginReport. Esse objeto representa o relatório que o usuário receberá ao final da síntese.

validate(context: IPolicyValidationContext): PolicyValidationPluginReport {
  // First read the templates using context.templatePaths...
  // ...then perform the validation, and then compose and return the report.
  // Using hard-coded values here for better clarity:
  return {
    success: false,
    violations: [{
      ruleName: 'CKV_AWS_117',
      description: 'Ensure that AWS Lambda function is configured inside a VPC',
      fix: 'https://docs.bridgecrew.io/docs/ensure-that-aws-lambda-function-is-configured-inside-a-vpc-1',
      violatingResources: [{
        resourceName: 'MyFunction3BAA72D1',
        templatePath: '/home/johndoe/myapp/cdk.out/MyService.template.json',
        locations: 'Properties/VpcConfig',
      }],
    }],
  };
}

Observe que os plug-ins não podem modificar nada no conjunto de nuvem. Qualquer tentativa de fazer isso resultará em falha na síntese.

Se seu plug-in depender de uma ferramenta externa que você usa, lembre-se de que alguns desenvolvedores talvez ainda não tenham essa ferramenta instalada em suas estações de trabalho. Para minimizar o atrito, forneça um script de instalação junto com seu pacote de plug-in para automatizar o processo de instalação.

Tratamento de exceções

Se sua organização tiver um mecanismo para lidar com exceções, ele poderá ser implementado como parte do plug-in validador.

Um exemplo de cenário para ilustrar um possível mecanismo de exceção:

Nesse cenário, o desenvolvedor solicitaria uma exceção no sistema interno e, em seguida, precisaria de alguma forma de “registrar” essa exceção. Além do exemplo do plug-in de proteção, você pode criar um plug-in que lida com exceções filtrando as violações que têm uma exceção correspondente em um sistema interno de tickets.

Veja os plug-ins existentes para ver exemplos de implementações.