Skip to content

Latest commit

 

History

History
221 lines (129 loc) · 8.88 KB

DEPLOYMENT_REFERENCE.md

File metadata and controls

221 lines (129 loc) · 8.88 KB

Deployment guidelines

This document describes configuration reference for CloudFormation template.yaml.

The template is designed to require a single mandatory parameter to deploy a working CloneSquad: GroupName. All other parameters can be left with their respective defaults.

GroupName

Required: Yes
Format: String

The CloneSquad deployment is looking for resources with a clonesquad:group-name tag containing this value. CloneSquad uses this tag/value to know which resources (EC2, RDS...) belongs to its duty.

LambdaMemorySize

Required: No
Format: Integer

Memory (MBytes) allocated to Main and Interact Lambda functions.

  • Minimum: 512
  • Maximum: 1792

As the Main Lambda function is mostly CPU bound, increasing memory to 1792 MBytes will ensure allocation of one full vCPU providing the maximum possible compute power the Lambda functions.

It is useless to give more memory than 1792 MBytes as the Main Lambda function is purely mono-threaded.

ApiGWConfiguration

Required: No
Format: MetaString

ApiGWConfiguration=[REGIONAL|PRIVATE],GWPolicy=<url_to_a_json_resource_file>,VpcEndpointDNS=vpce-0aaaaaaaaaaaaaaaa-bbbbbbbb.execute-api.eu-west-1.vpce.amazonaws.com,VpcId=vpc-0xxxxxxxxx
  • [REGIONAL|PRIVATE]: By default, the API Gateway is a REGIONAL one. This switch allows to define explicitly if the API Gateway is private or public regional.
  • GWPolicy: (Optional) Url to a customized API Gateway resource policy file. By default, the policy api-gw-default-policy.json is automatically loaded. This default policy allows access only to AWS_IAM authenticated requests coming from the resource located in the AWS account where CloneSquad is deployed.

The 2 optional parameters defined below are used to populate the 'ApiGwVpcEndpointDNSEntry' field in the Discovery API/Lambda. If not set, the VPC endpoint DNS name is guessed from ApiGWEndpointConfiguration (if defined). Setting these parameters is useful to propagate the VPC Endpoint DNS names to external software that needs an automatic discovery (The cs-instance-watcher is using this information). This parameter is mainly useful when the endpoint is configured with PrivateDnsEnabled set to False.

  • VpcEndpointDNS: (Optional) When ApiGWEndpointConfiguration is not defined, this value is used.
  • VpcId: (Optional) If set to a valid VPC Id, the prefered VPC Endpoint to use to access the API is guessed by describing the specified VPC.

Note: If you have no use of the 'ApiGwVpcEndpointDNSEntry' discovery field, you can safely let these parameters undefined.

ApiGWEndpointConfiguration

Required: No
Format: MetaString

ApiGWEndpointConfiguration=VpcId=vpc-12345678,VpcEndpointPolicyURL=<url_to_policy_file>,SubnetIds=<subent_id_list>,TrustedClients=<list_of_rules>

This parameter controls the creation of VPC Endpoints to access the API Gateway from a specified VpcId.

By default, no VPC Endpoints are created: This is intended to allow CloneSquad deployment in an account that uses VPC Sharing mechanism. When the API Gateway needs to be accessed from a VPC Shared, leave this field empty and create manually the required VPC Endpoints from the AWS Account owning the shared VPC.

  • VpcId: (Required) VPC Id where to deploy VPC Endpoints to access the CloneSquad API Gateway.
  • VpcEndpointPolicyURL: (Optional) Url to a VPC Endpoint policy file. By default, the policy api-gw-default-endpoint-policy.json. This policy allows AWS_IAM authenticated requests from specified VpcId.
  • SubnetIds: (Optional) Coma separated list of subnet Ids where to create a VPC Endpoint. By default, VPC Endpoints are deployed in all subnets of the specified VPcId.
    • Note: Comas MUST be backslashed!
  • PrivateDnsEnabled: (Optional) Default value is True.
  • TrustedClients: (Optional) List of trusted sources for VPC Endpoint Security Group igress rules. Security groups, prefix lists and IP CIDR can be specified with a coma separated list. By default, 0.0.0.0/0 is defined as the igress rule.
    • Note: Comas MUST be backslashed!

UserSuppliedJSONMetadata

Required: No
Format: String

UserSuppliedJSONMetadata={"Hello": "the", "world": "!!"}

This JSON snippet only purpose is to be forwarded and stored in the AWS Athena clonesquad_discovery table (see discovery metadata).

Typical usage for this parameter is to add user specific data that would be queriable in the CloneSquad centralized CMDB.

MetadataAndBackupS3Path

Required: No
Format: String

MetadataAndBackupS3Path=s3://<bucketname>/<directorypath>

S3 location where to send configuration backups and metadata.

These data are generated on-demand (through the API Gateway) or periodically with a cron setting.

Note: Setting this parameter enables automatically an hourly backup and metadata generation. Please see documentation if this behavior needs to be modified.

LoggingS3Path

Required: No
Format: String

LoggingS3Path=s3://<bucketname>/<objectpath>

S3 location where to send Debug reports.

When specified, on critical error (ex: Python exception), CloneSquad will generate a debug report as a Zip file that will be pushed in this S3 path.

UserNotificationArns

Required: No
Format: StringList

UserNotificationArns=<Target notification ARN>,...

Coma separated list of notification targets. Can be Lambda, SQS or SNS ARNs.

ConfigurationURLs

Required: No
Format: StringList

ConfigurationURLs=<Url_to_a_YAML_file>;...

Semicolon separated list of YAML files to load as configuration ones.

DynamoDBConfiguration

Required: No
Format: MetaString

By defaut, DynamoDB tables are configured to use On-Demand capacity provisionning. This parameter allows to switch to PROVISIONED capacity and so reduce costs.

Tip: Observe the tables metrics over a relevant period of time and determine the appropriate ReadCapacityUnits and WriteCapacityUnits for each tables. WARNING: Do not make a table throttle by setting too low values as it will generate Python exceptions preventing normal CloneSquad operations.

Coma separated list of DynamoDB Table PROVISIONED throughput. Table name must be one of ["ConfigTable", "AlarmStateEC2Table", "EventTable", "LongTermEventTable", "SchedulerTable", "StateTable"]

ApiGWConfiguration=<TableName>=<ReadCapacityUnits>:<WriteCapacityUnits>,...
Ex: ApiGWConfiguration=StateTable=3:3,EventTable=2:5

CustomizationZipParameters

Required: No
Format: String

CustomizationZipParameters=<Zip customization file description>

Path to a ZIP file located in S3 expressed with the special format '<S3_bucket_name>:<S3_key_path>'.

TimeZone

Required: No
Format: String

TimeZone=<TZ specification>

A time zone specification following the TZ format (ex: Europe/Paris, America/Los_Angeles...)

To list all valid timezones, use the following command:

python3 -c "import dateutil.zoneinfo ; print(list(dateutil.zoneinfo.get_zonefile_instance().zones.keys()))"

LogLevels

Required: No
Format: StringList

LogLevels=<module=LEVEL>,<module=LEVEL>...

Module names are the Python filenames contained in the Github repository named src/ (ex: kvtable.py => kvtable module name).

Ex: Activate maximum verbosity of logs in all modules.

LogLevels=*=DEBUG

PermissionBoundary

Required: No
Format: ARN string

Specify an optional IAM policy ARN as boundary for all roles created by the CloudFormation template.

InteractSQSQueueIAMPolicy

Required: No
Format: JSON document

Specify an optional IAM policy condition in the IAM policy protecting the InteractSQSQueue. This queue is used to acknowledge Events sent to targets listed in UserNotificationArns.

By defaut, only current AWS Account principals are allowed to send a message to this queue. This parameter allows to define Principal: and Condition: statements to restrict these default accesses.

As an example, this JSON document can be inlined in this parameter to allow access to any account in the AWS Organization Id named o-xxxxxxxxxx:

{"Principal":{"AWS":"*"},"Condition":{"StringEquals":{"aws:PrincipalOrgID":"o-xxxxxxxxxx"}}}

EBSVolumeKMSKeys

Required: No
Format: Coma separated list of KMS key ARNs

By default, CloneSquad Lambda functions have access to all KMS Keys in order to start any EC2 instances with an EBS encrypted volume. Setting this value with a coma-separated list of KMS key ARNs will restrict these broad access to the listed keys only.