# aws-fargate-sns
<a name="aws_fargate_sns"></a>

![\[Stability:Experimental\]](https://img.shields.io/badge/stability-Experimental-important.svg?style=for-the-badge)


All classes are under active development and subject to non-backward compatible changes or removal in any future version. These are not subject to the [Semantic Versioning](https://semver.org/) model. This means that while you may use them, you may need to update your source code when upgrading to a newer version of this package.


|  |  | 
| --- |--- |
|  Reference Documentation: | https://docs.aws.amazon.com/solutions/latest/constructs/ | 


|  **Language**  |  **Package**  | 
| --- | --- | 
|   ![\[Python Logo\]](https://docs.aws.amazon.com/images/solutions/latest/constructs/images/python32.png) Python  |   `aws_solutions_constructs.aws_fargate_sns`   | 
|   ![\[Typescript Logo\]](https://docs.aws.amazon.com/images/solutions/latest/constructs/images/typescript32.png) Typescript  |   `@aws-solutions-constructs/aws-fargate-sns`   | 
|   ![\[Java Logo\]](https://docs.aws.amazon.com/images/solutions/latest/constructs/images/java32.png) Java  |   `software.amazon.awsconstructs.services.fargatesns`   | 

## Overview
<a name="_overview"></a>

This AWS Solutions Construct implements an AWS Fargate service that can write to an Amazon SNS topic

Here is a minimal deployable pattern definition:

**Example**  

```
import { Construct } from 'constructs';
import { Stack, StackProps } from 'aws-cdk-lib';
import { FargateToSns, FargateToSnsProps } from '@aws-solutions-constructs/aws-fargate-sns';

const constructProps: FargateToSnsProps = {
    publicApi: true,
    ecrRepositoryArn: "arn:aws:ecr:us-east-1:123456789012:repository/your-ecr-repo"
};

new FargateToSns(this, 'test-construct', constructProps);
```

```
from aws_solutions_constructs.aws_fargate_sns import FargateToSns, FargateToSnsProps
from aws_cdk import (
    Stack
)
from constructs import Construct

FargateToSns(self, 'test_construct',
            public_api=True,
            ecr_repository_arn="arn:aws:ecr:us-east-1:123456789012:repository/your-ecr-repo")
```

```
import software.constructs.Construct;

import software.amazon.awscdk.Stack;
import software.amazon.awscdk.StackProps;
import software.amazon.awsconstructs.services.fargatesns.*;

new FargateToSns(this, "test_construct", new FargateToSnsProps.Builder()
        .publicApi(true)
        .ecrRepositoryArn("arn:aws:ecr:us-east-1:123456789012:repository/your-ecr-repo")
        .build());
```

## Pattern Construct Props
<a name="_pattern_construct_props"></a>


|  **Name**  |  **Type**  |  **Description**  | 
| --- | --- | --- | 
|  publicApi  |  boolean  |  Whether the construct is deploying a private or public API. This has implications for the VPC.  | 
|  vpcProps?  |   [ec2.VpcProps](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_ec2.VpcProps.html)   |  Optional custom properties for a VPC the construct will create. This VPC will be used by any Private Hosted Zone the construct creates (that’s why loadBalancerProps and privateHostedZoneProps can’t include a VPC). Providing both this and existingVpc causes an error.  | 
|  existingVpc?  |   [ec2.IVpc](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_ec2.IVpc.html)   |  An existing VPC in which to deploy the construct. Providing both this and vpcProps causes an error. If the client provides an existing load balancer and/or existing Private Hosted Zone, those constructs must exist in this VPC.  | 
|  clusterProps?  |   [ecs.ClusterProps](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_ecs.ClusterProps.html)   |  Optional properties to create a new ECS cluster. To provide an existing cluster, use the cluster attribute of fargateServiceProps.  | 
|  ecrRepositoryArn?  |  string  |  The arn of an ECR Repository containing the image to use to generate the containers. Either this or the image property of containerDefinitionProps must be provided. format: arn:aws:ecr:\$1region\$1:\$1account number\$1:repository/*Repository Name*   | 
|  ecrImageVersion?  |  string  |  The version of the image to use from the repository. Defaults to "Latest"   | 
|  containerDefinitionProps?  |   [ecs.ContainerDefinitionProps \$1 any](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_ecs.ContainerDefinitionProps.html)   |  Optional props to define the container created for the Fargate Service (defaults found in fargate-defaults.ts)  | 
|  fargateTaskDefinitionProps?  |   [ecs.FargateTaskDefinitionProps \$1 any](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_ecs.FargateTaskDefinitionProps.html)   |  Optional props to define the Fargate Task Definition for this construct (defaults found in fargate-defaults.ts)  | 
|  fargateServiceProps?  |   [ecs.FargateServiceProps \$1 any](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_ecs.FargateServiceProps.html)   |  Optional values to override default Fargate Task definition properties (fargate-defaults.ts). The construct will default to launching the service is the most isolated subnets available (precedence: Isolated, Private and Public). Override those and other defaults here.  | 
|  existingFargateServiceObject?  |   [ecs.FargateService](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_ecs.FargateService.html)   |  A Fargate Service already instantiated (probably by another Solutions Construct). If this is specified, then no props defining a new service can be provided, including: ecrImageVersion, containerDefinitionProps, fargateTaskDefinitionProps, ecrRepositoryArn, fargateServiceProps, clusterProps  | 
|  existingContainerDefinitionObject?  |   [ecs.ContainerDefinition](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_ecs.ContainerDefinition.html)   |  A container definition already instantiated as part of a Fargate service. This must be the container in the existingFargateServiceObject  | 
|  existingTopicObj?  |   [sns.Topic](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_sns.Topic.html)   |  Existing instance of SNS Topic object, providing both this and `topicProps` will cause an error.  | 
|  topicProps?  |   [sns.TopicProps](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_sns.TopicProps.html)   |  Optional - user provided properties to override the default properties for the SNS topic. Providing both this and `existingTopicObj` causes an error.  | 
|  topicArnEnvironmentVariableName?  |  string  |  Optional Name for the container environment variable set to the ARN of the topic. Default: SNS\$1TOPIC\$1ARN  | 
|  topicNameEnvironmentVariableName?  |  string  |  Optional Name for the container environment variable set to the name of the topic. Default: SNS\$1TOPIC\$1NAME  | 
|  enableEncryptionWithCustomerManagedKey?  |   `boolean`   |  If no key is provided, this flag determines whether the SNS Topic is encrypted with a new CMK or an AWS managed key. This flag is ignored if any of the following are defined: topicProps.masterKey, encryptionKey or encryptionKeyProps.  | 
|  encryptionKey?  |   [https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_kms.Key.html](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_kms.Key.html)   |  An optional, imported encryption key to encrypt the SNS Topic with.  | 
|  encryptionKeyProps?  |   [https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_kms.Key.html#construct-props](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_kms.Key.html#construct-props)   |  Optional user provided properties to override the default properties for the KMS encryption key used to encrypt the SNS Topic with.  | 

## Pattern Properties
<a name="_pattern_properties"></a>


|  **Name**  |  **Type**  |  **Description**  | 
| --- | --- | --- | 
|  vpc  |   [ec2.IVpc](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_ec2.IVpc.html)   |  The VPC used by the construct (whether created by the construct or provided by the client)  | 
|  service  |   [ecs.FargateService](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_ecs.FargateService.html)   |  The AWS Fargate service used by this construct (whether created by this construct or passed to this construct at initialization)  | 
|  container  |   [ecs.ContainerDefinition](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_ecs.ContainerDefinition.html)   |  The container associated with the AWS Fargate service in the service property.  | 
|  snsTopic  |   [https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_sns.Topic.html](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_sns.Topic.html)   |  Returns an instance of the SNS topic created by the pattern.  | 

## Default settings
<a name="_default_settings"></a>

Out of the box implementation of the Construct without any override will set the following defaults:

### AWS Fargate Service
<a name="_aws_fargate_service"></a>
+ Sets up an AWS Fargate service
  + Uses the existing service if provided
  + Creates a new service if none provided.
    + Service will run in isolated subnets if available, then private subnets if available and finally public subnets
  + Adds environment variables to the container with the ARN and Name of the SNS topic
  + Add permissions to the container IAM role allowing it to publish to the SNS topic

### Amazon SNS Topic
<a name="_amazon_sns_topic"></a>
+ Sets up an Amazon SNS topic
  + Uses an existing topic if one is provided, otherwise creates a new one
+ Adds an Interface Endpoint to the VPC for SNS (the service by default runs in Isolated or Private subnets)

## Architecture
<a name="_architecture"></a>

![\[Diagram showing the Fargate service, SNS topic and IAM role created by the construct\]](http://docs.aws.amazon.com/solutions/latest/constructs/images/aws-fargate-sns.png)


## Github
<a name="_github"></a>

Go to the [Github repo](https://github.com/awslabs/aws-solutions-constructs/tree/main/source/patterns/%40aws-solutions-constructs/aws-fargate-sns) for this pattern to view the code, read/create issues and pull requests and more.