cfn-cr-synapse-tagger

Cloudformation Custom Resource used to apply tags to resources provisioned using the Sage Service Catalog.

Inventory of source code and supporting files:

• set_tags - Function to set tags on resources.
• events - Invocation events that you can use to invoke the function.
• tests - Unit tests for the application code.
• template.yaml - A template that defines the application's AWS resources.

The AWS SAM CLI is used to build and package the lambda code. The sceptre utility is used to deploy the macro that invokes the lambda as a CloudFormation stack.

Prerequisites

This custom resource only works with when used with the Synapse IDP and the AWS Service Catalog.

AWS will apply the following tags when resources are provisioned with the Service Catalog:

Key	Value (something like)
aws:servicecatalog:provisioningPrincipalArn	arn:aws:sts::123456712:assumed-role/ServiceCatalogEndusers/1234567
aws:servicecatalog:provisionedProductArn	arn:aws:servicecatalog:us-east-1:123456712:stack/my-product/pp-mycpuogt2i45s

This custom resource uses these tags to retrieve more information and applies them as additional tags on the provisioned resource.

Supported Tags

All Resources

• Synapse tags - Retrieve the Synapse userProfile info and apply a subset of that data as tags to resources.

EC2 Only

• AccessApprovedCaller tag - Generate the info to allow role access to an instance and apply it as a tag on the resource.

Parameters

This custom resource assumes the existence of the following SSM parameters:

• /service-catalog/TeamToRoleArnMap - used to determine and apply the Synapse team tag

The specification for these parameters are defined by the synapse login app.

Use in a Cloudformation Template

S3 Bucket

Create a custom resource in your cloudformation template. Here's an example:

  TagBucket:
    Type: Custom::SynapseTagger
    Properties:
      ServiceToken: !ImportValue
        'Fn::Sub': '${AWS::Region}-cfn-cr-synapse-tagger-SetBucketTagsFunctionArn'
      BucketName: !Ref MyBucket

The creation of the custom resource triggers the lambda, which pulls the current tags from S3Bucket, derives new tags, and sets those on the bucket. Currently the only new tag added is an OwnerEmail tag, whose value looks like [email protected], where the janedoe is a Synapse user name. Synapse provides email addresses for all user names.

EC2 Instance

Create a custom resource in your cloudformation template. Here's an example:

  TagInstance:
    Type: Custom::SynapseTagger
    Properties:
      ServiceToken: !ImportValue
        'Fn::Sub': '${AWS::Region}-cfn-cr-synapse-tagger-SetInstanceTagsFunctionArn'
      InstanceId: !Ref MyEC2

The creation of the custom resource triggers the lambda, which pulls the current tags from MyEC2 instance, derives new tags, and sets those on the instance.

Scheduled Jobs (Batch)

Create a custom resource in your cloudformation template. Here's an example:

  BatchTagger:
    Type: Custom::SynapseTagger
    Properties:
      ServiceToken: !ImportValue
        'Fn::Sub': '${AWS::Region}-cfn-cr-synapse-tagger-SetBatchTagsFunctionArn'
      BatchResources:
        JobDefinitionArn: !Ref JobDefinition
        JobQueueArn: !Ref JobQueue
        ComputeEnvironmentArn: !Ref ComputeEnvironment
        SchedulingPolicyArn: !Ref SchedulingPolicy

Development

Contributions

Contributions are welcome.

Setup Development Environment

Install the following applications:

• AWS CLI
• AWS SAM CLI
• pre-commit
• pipenv

Install Requirements

Run pipenv install --dev to install both production and development requirements, and pipenv shell to activate the virtual environment. For more information see the pipenv docs.

After activating the virtual environment, run pre-commit install to install the pre-commit git hook.

Update Requirements

First, make any needed updates to the base requirements in Pipfile, then use pipenv to regenerate both Pipfile.lock and requirements.txt.

$ pipenv update --dev

We use pipenv to control versions in testing, but sam relies on requirements.txt directly for building the lambda artifact, so we dynamically generate requirements.txt from Pipfile.lock before building the artifact. The file must be created in the CodeUri directory specified in template.yaml.

$ pipenv requirements > requirements.txt

Additionally, pre-commit manages its own requirements.

$ pre-commit autoupdate

Create a local build

Use a Lambda-like docker container to build the Lambda artifact

$ sam build --use-container

Run unit tests

Tests are defined in the tests folder in this project, and dependencies are managed with pipenv. Install the development dependencies and run the tests using coverage.

$ pipenv run coverage run -m pytest tests/ -svv

Automated testing will upload coverage results to Coveralls.

Run integration tests

Running integration tests requires docker

$ sam local invoke SetBatchTagsFunction --event events/set_batch_tags
$ sam local invoke SetBucketTagsFunction --event events/set_bucket_tags
$ sam local invoke SetInstanceTagsFunction --event events/set_instance_tags

Deployment

Deploy Lambda to S3

Deployments are sent to the Sage cloudformation repository which requires permissions to upload to Sage bootstrap-awss3cloudformationbucket-19qromfd235z9 and essentials-awss3lambdaartifactsbucket-x29ftznj6pqw buckets.

sam package --template-file .aws-sam/build/template.yaml \
  --s3-bucket essentials-awss3lambdaartifactsbucket-x29ftznj6pqw \
  --output-template-file .aws-sam/build/cfn-cr-synapse-tagger.yaml

aws s3 cp .aws-sam/build/cfn-cr-synapse-tagger.yaml s3://bootstrap-awss3cloudformationbucket-19qromfd235z9/cfn-cr-synapse-tagger/master/

Publish Lambda

Private access

Publishing the lambda makes it available in your AWS account. It will be accessible in the serverless application repository.

sam publish --template .aws-sam/build/cfn-cr-synapse-tagger.yaml

Public access

Making the lambda publicly accessible makes it available in the global AWS serverless application repository

aws serverlessrepo put-application-policy \
  --application-id <lambda ARN> \
  --statements Principals=*,Actions=Deploy

Install Lambda into AWS

Sceptre

Create the following sceptre file

config/prod/cfn-cr-synapse-tagger.yaml

template:
  type: http
  url: "https://s3.amazonaws.com/essentials-awss3lambdaartifactsbucket-x29ftznj6pqw/it-lambda-set-bucket-tags/master/cfn-cr-synapse-tagger.yaml"
stack_name: "cfn-cr-synapse-tagger"

Install the lambda using sceptre:

sceptre --var "profile=my-profile" --var "region=us-east-1" launch prod/cfn-cr-synapse-tagger

AWS Console

Steps to deploy from AWS console.

1. Login to AWS
2. Access the serverless application repository -> Available Applications
3. Select application to install
4. Enter Application settings
5. Click Deploy