Cloudformation Extension - Activation Guide

📖 Cloudformation Registry

Cloudformation Provides registry extensions to use in the Cloudformation template through which we can create custom resources, manage or view resource configuraitons at the build time of the Cloudformation stack. More on the AWS Cloudformation Docs

The CloudFormation registry lets you manage extensions, both public and private, such as resources, modules, and hooks that are available for use in your AWS account. Currently, you can use the following extension types in the AWS registry: resources types, modules, and hooks. The registry makes it easier to discover and provision extensions in your AWS CloudFormation templates in the same manner you use AWS-provided resources.

In this guide, we will be using Serverless framework to write the CF template.

Note: We can only deploy the activation resources once as we can only Activate the extension one time in a single AWS Account. Deploying same after the extension is activated might throw error in the Cloudformation.

🛠 Extension Setup & Configurations

Cloudformation Extensions require Execution Role which can help extension perform certain actions for the resource we want to create or manage.

Additionally we can provide the Logging Config which can help log the events from the extensions. We can also pass Extention Configurations to have any additional configurations added to the extension at run time.

💡Extension Activation

In this article we will try to activate public third party extensions of different types.

First we will create execution role which can be used by the Extensions to perform actions on Cloudformation Resources.

🔐 Execution Role

You can define more permissions in the role policy if you need to attach other service policies.

ExecutionRole: {
    Type: "AWS::IAM::Role",
    Properties: {
      Path: "/",
      RoleName: `ExtensionExecutionRule`,
      Description: "IAM Role Execution role for Cloudformation Extension",
      MaxSessionDuration: 8400,
      AssumeRolePolicyDocument: {
        Version: "2012-10-17",
        Statement: [
          {
            Effect: "Allow",
            Principal: {
              Service: [
                "hooks.cloudformation.amazonaws.com",
                "resources.cloudformation.amazonaws.com",
              ],
            },
            Action: "sts:AssumeRole",
          },
        ],
      },
    },
  }

Resource Type

Github::Repository::Secret is a public third party RESOURCE type extension.

GithubRepoSecretExtensionActivation: {
  Type: "AWS::CloudFormation::TypeActivation",
  Properties: {
    AutoUpdate: true,
    ExecutionRoleArn: {
      "Fn::GetAtt": ["ExecutionRole", "Arn"],
    },
        LoggingConfig: {
            LogGroupName : {
                Ref: "GithubRepoSecretExtensionLogGroup"
            },
          LogRoleArn : ["ExtensionLogRole", "Arn"]
        }
    PublicTypeArn: {
      "Fn::Join": [
        "",
        [
          "arn:aws:cloudformation:",
          { Ref: "AWS::Region" },
          "::type/resource/c830e97710da0c9954d80ba8df021e5439e7134b/GitHub-Repositories-Secret",
        ],
      ],
    },
    Type: "RESOURCE",
    TypeName: "GitHub::Repositories::Secret",
    VersionBump: "MAJOR",
  },
}

Module Type

JFrog::Vpc::MultiAz::MODULE is a public third party MODULE resource.

JFrogModuleExtensionActivation: {
  Type: "AWS::CloudFormation::TypeActivation",
  Properties: {
    AutoUpdate: true,
    ExecutionRoleArn: {
      "Fn::GetAtt": ["ExecutionRole", "Arn"],
    },
        LoggingConfig: {
            LogGroupName : {
                Ref: "JFrogModuleExtensionLogGroup"
            },
          LogRoleArn : ["ExtensionLogRole", "Arn"]
        }
    PublicTypeArn: {
      "Fn::Join": [
        "",
        [
          "arn:aws:cloudformation:",
          { Ref: "AWS::Region" },
          "::type/module/06ff50c2e47f57b381f874871d9fac41796c9522/JFrog-Vpc-MultiAz-MODULE",
        ],
      ],
    },
    Type: "MODULE",
    TypeName: "JFrog::Vpc::MultiAz::MODULE",
    VersionBump: "MAJOR",
  },
}

Hooks Type

Generic::SecretsProtection::Hook is a third party HOOK resource type.

GenericSecretsProtectionHookExtensionActivation: {
  Type: "AWS::CloudFormation::TypeActivation",
  Properties: {
    AutoUpdate: true,
    ExecutionRoleArn: {
      "Fn::GetAtt": ["ExecutionRole", "Arn"],
    },
        LoggingConfig: {
            LogGroupName : {
                Ref: "GenericSecretsProtectionHookExtensionLogGroup"
            },
          LogRoleArn : ["ExtensionLogRole", "Arn"]
        }
    PublicTypeArn: {
      "Fn::Join": [
        "",
        [
          "arn:aws:cloudformation:",
          { Ref: "AWS::Region" },
          "::type/hook/e1238fdd31aee1839e14fb3fb2dac9db154dae29/Generic-SecretsProtection-Hook",
        ],
      ],
    },
    Type: "HOOK",
    TypeName: "Generic::SecretsProtection::Hook",
    VersionBump: "MAJOR",
  },
}

In addition to these fields you can pass TypeNameAlias properties which can be set to any custom values developer wants. And can be used in Cloudformation using that Alias Name. You can find all the properties for Cloudformation TypeActivation in AWS Docs.

⚙️ Setting up Extension Configurations

If the extension needs any additional configurations needed then we can set them using an AWS CLI command

aws cloudformation set-type-configuration --type-name "GitHub::Repositories::Secret" --type RESOURCE --configuration-alias ConfigurationName --configuration '{"Credentials": {"ApiKey": "abc", "ApplicationKey": "abc"}}'

Note: If you specify TypeNameAlias field when extension activation, you’ll need to enter that Alias as --type-name while executing above command to set type configurations.

Hope this help a developer in need! 🎁