feat(images): additions to SAM spec (#1845)

New properties in AWS::Serverless::Function

ImageUri -> Code: ImageUri -> AWS::Lambda::Function
ImageConfig -> Passthrough -> AWS::Lambda::Function
PackageType -> Passthrough -> AWS::Lambda::Function

Author: sriram-mv

samtranslator/__init__.py

@@ -1 +1 @@
-__version__ = "1.31.0"
+__version__ = "1.32.0"

samtranslator/model/lambda_.py

@@ -7,10 +7,11 @@ class LambdaFunction(Resource):
     resource_type = "AWS::Lambda::Function"
     property_types = {
         "Code": PropertyType(True, is_type(dict)),
+        "PackageType": PropertyType(False, is_str()),
         "DeadLetterConfig": PropertyType(False, is_type(dict)),
         "Description": PropertyType(False, is_str()),
         "FunctionName": PropertyType(False, is_str()),
-        "Handler": PropertyType(True, is_str()),
+        "Handler": PropertyType(False, is_str()),
         "MemorySize": PropertyType(False, is_type(int)),
         "Role": PropertyType(False, is_str()),
         "Runtime": PropertyType(False, is_str()),
@@ -24,6 +25,7 @@ class LambdaFunction(Resource):
         "ReservedConcurrentExecutions": PropertyType(False, any_type()),
         "FileSystemConfigs": PropertyType(False, list_of(is_type(dict))),
         "CodeSigningConfigArn": PropertyType(False, is_str()),
+        "ImageConfig": PropertyType(False, is_type(dict)),
     }
 
     runtime_attrs = {"name": lambda self: ref(self.logical_id), "arn": lambda self: fnGetAtt(self.logical_id, "Arn")}

samtranslator/model/packagetype.py

@@ -0,0 +1,2 @@
+IMAGE = "Image"
+ZIP = "Zip"

samtranslator/model/s3_utils/uri_parser.py

@@ -45,6 +45,24 @@ def to_s3_uri(code_dict):
     return uri
 
 
+def construct_image_code_object(image_uri, logical_id, property_name):
+    """Constructs a Lambda `Code` or `Content` property, from the SAM `ImageUri` property.
+    This follows the current scheme for Lambda Functions.
+
+    :param string image_uri: string
+    :param string logical_id: logical_id of the resource calling this function
+    :param string property_name: name of the property which is used as an input to this function.
+    :returns: a Code dict, containing the ImageUri.
+    :rtype: dict
+    """
+    if not image_uri:
+        raise InvalidResourceException(
+            logical_id, "'{}' requires that a image hosted at a registry be specified.".format(property_name)
+        )
+
+    return {"ImageUri": image_uri}
+
+
 def construct_s3_location_object(location_uri, logical_id, property_name):
     """Constructs a Lambda `Code` or `Content` property, from the SAM `CodeUri` or `ContentUri` property.
     This follows the current scheme for Lambda Functions and LayerVersions.

samtranslator/model/sam_resources.py

@@ -7,7 +7,8 @@
 import samtranslator.model.eventsources.cloudwatchlogs
 from .api.api_generator import ApiGenerator
 from .api.http_api_generator import HttpApiGenerator
-from .s3_utils.uri_parser import construct_s3_location_object
+from .packagetype import ZIP, IMAGE
+from .s3_utils.uri_parser import construct_s3_location_object, construct_image_code_object
 from .tags.resource_tagging import get_tag_list
 from samtranslator.model import PropertyType, SamResourceMacro, ResourceTypeResolver
 from samtranslator.model.apigateway import (
@@ -54,9 +55,11 @@ class SamFunction(SamResourceMacro):
     resource_type = "AWS::Serverless::Function"
     property_types = {
         "FunctionName": PropertyType(False, one_of(is_str(), is_type(dict))),
-        "Handler": PropertyType(True, is_str()),
-        "Runtime": PropertyType(True, is_str()),
+        "Handler": PropertyType(False, is_str()),
+        "Runtime": PropertyType(False, is_str()),
         "CodeUri": PropertyType(False, one_of(is_str(), is_type(dict))),
+        "ImageUri": PropertyType(False, is_str()),
+        "PackageType": PropertyType(False, is_str()),
         "InlineCode": PropertyType(False, one_of(is_str(), is_type(dict))),
         "DeadLetterQueue": PropertyType(False, is_type(dict)),
         "Description": PropertyType(False, is_str()),
@@ -82,6 +85,7 @@ class SamFunction(SamResourceMacro):
         "VersionDescription": PropertyType(False, is_str()),
         "ProvisionedConcurrencyConfig": PropertyType(False, is_type(dict)),
         "FileSystemConfigs": PropertyType(False, list_of(is_type(dict))),
+        "ImageConfig": PropertyType(False, is_type(dict)),
         "CodeSigningConfigArn": PropertyType(False, is_str()),
     }
     event_resolver = ResourceTypeResolver(
@@ -406,6 +410,8 @@ def _construct_lambda_function(self):
         lambda_function.Tags = self._construct_tag_list(self.Tags)
         lambda_function.Layers = self.Layers
         lambda_function.FileSystemConfigs = self.FileSystemConfigs
+        lambda_function.ImageConfig = self.ImageConfig
+        lambda_function.PackageType = self.PackageType
 
         if self.Tracing:
             lambda_function.TracingConfig = {"Mode": self.Tracing}
@@ -415,6 +421,7 @@ def _construct_lambda_function(self):
 
         lambda_function.CodeSigningConfigArn = self.CodeSigningConfigArn
 
+        self._validate_package_type(lambda_function)
         return lambda_function
 
     def _add_event_invoke_managed_policy(self, dest_config, logical_id, condition, dest_arn):
@@ -491,6 +498,50 @@ def _construct_role(self, managed_policy_map, event_invoke_policies):
         )
         return execution_role
 
+    def _validate_package_type(self, lambda_function):
+        """
+        Validates Function based on the existence of Package type
+        """
+        packagetype = lambda_function.PackageType or ZIP
+
+        if packagetype not in [ZIP, IMAGE]:
+            raise InvalidResourceException(
+                lambda_function.logical_id,
+                "PackageType needs to be `{zip}` or `{image}`".format(zip=ZIP, image=IMAGE),
+            )
+
+        def _validate_package_type_zip():
+            if not all([lambda_function.Runtime, lambda_function.Handler]):
+                raise InvalidResourceException(
+                    lambda_function.logical_id,
+                    "Runtime and Handler needs to be present when PackageType is of type `{zip}`".format(zip=ZIP),
+                )
+
+            if any([lambda_function.Code.get("ImageUri", False), lambda_function.ImageConfig]):
+                raise InvalidResourceException(
+                    lambda_function.logical_id,
+                    "ImageUri or ImageConfig cannot be present when PackageType is of type `{zip}`".format(zip=ZIP),
+                )
+
+        def _validate_package_type_image():
+            if any([lambda_function.Handler, lambda_function.Runtime, lambda_function.Layers]):
+                raise InvalidResourceException(
+                    lambda_function.logical_id,
+                    "Runtime, Handler, Layers cannot be present when PackageType is of type `{image}`".format(
+                        image=IMAGE
+                    ),
+                )
+            if not lambda_function.Code.get("ImageUri"):
+                raise InvalidResourceException(
+                    lambda_function.logical_id,
+                    "ImageUri needs to be present when PackageType is of type `{image}`".format(image=IMAGE),
+                )
+
+        _validate_per_package_type = {ZIP: _validate_package_type_zip, IMAGE: _validate_package_type_image}
+
+        # Call appropriate validation function based on the package type.
+        return _validate_per_package_type[packagetype]()
+
     def _validate_dlq(self):
         """Validates whether the DeadLetterQueue LogicalId is validation
         :raise: InvalidResourceException
@@ -577,12 +628,59 @@ def _generate_event_resources(
         return resources
 
     def _construct_code_dict(self):
-        if self.InlineCode:
+        """Constructs Lambda Code Dictionary based on the accepted SAM artifact properties such
+        as `InlineCode`, `CodeUri` and `ImageUri` and also raises errors if more than one of them is
+        defined. `PackageType` determines which artifacts are considered.
+
+        :raises InvalidResourceException when conditions on the SAM artifact properties are not met.
+        """
+        # list of accepted artifacts
+        packagetype = self.PackageType or ZIP
+        artifacts = {}
+
+        if packagetype == ZIP:
+            artifacts = {"InlineCode": self.InlineCode, "CodeUri": self.CodeUri}
+        elif packagetype == IMAGE:
+            artifacts = {"ImageUri": self.ImageUri}
+
+        if packagetype not in [ZIP, IMAGE]:
+            raise InvalidResourceException(self.logical_id, "invalid 'PackageType' : {}".format(packagetype))
+
+        # Inline function for transformation of inline code.
+        # It accepts arbitrary argumemnts, because the arguments do not matter for the result.
+        def _construct_inline_code(*args, **kwargs):
             return {"ZipFile": self.InlineCode}
-        elif self.CodeUri:
-            return construct_s3_location_object(self.CodeUri, self.logical_id, "CodeUri")
+
+        # dispatch mechanism per artifact on how it needs to be transformed.
+        artifact_dispatch = {
+            "InlineCode": _construct_inline_code,
+            "CodeUri": construct_s3_location_object,
+            "ImageUri": construct_image_code_object,
+        }
+
+        filtered_artifacts = dict(filter(lambda x: x[1] != None, artifacts.items()))
+        # There are more than one allowed artifact types present, raise an Error.
+        # There are no valid artifact types present, also raise an Error.
+        if len(filtered_artifacts) > 1 or len(filtered_artifacts) == 0:
+            if packagetype == ZIP and len(filtered_artifacts) == 0:
+                raise InvalidResourceException(self.logical_id, "Only one of 'InlineCode' or 'CodeUri' can be set.")
+            elif packagetype == IMAGE:
+                raise InvalidResourceException(self.logical_id, "'ImageUri' must be set.")
+
+        filtered_keys = [key for key in filtered_artifacts.keys()]
+        # NOTE(sriram-mv): This precedence order is important. It is protect against python2 vs python3
+        # dictionary ordering when getting the key values with .keys() on a dictionary.
+        # Do not change this precedence order.
+        if "InlineCode" in filtered_keys:
+            filtered_key = "InlineCode"
+        elif "CodeUri" in filtered_keys:
+            filtered_key = "CodeUri"
+        elif "ImageUri" in filtered_keys:
+            filtered_key = "ImageUri"
         else:
-            raise InvalidResourceException(self.logical_id, "Either 'InlineCode' or 'CodeUri' must be set")
+            raise InvalidResourceException(self.logical_id, "Either 'InlineCode' or 'CodeUri' must be set.")
+        dispatch_function = artifact_dispatch[filtered_key]
+        return dispatch_function(artifacts[filtered_key], self.logical_id, filtered_key)
 
     def _construct_version(self, function, intrinsics_resolver, code_sha256=None):
         """Constructs a Lambda Version resource that will be auto-published when CodeUri of the function changes.

tests/model/test_sam_resources.py

@@ -6,14 +6,14 @@
 from samtranslator.model import InvalidResourceException
 from samtranslator.model.apigatewayv2 import ApiGatewayV2HttpApi
 from samtranslator.model.lambda_ import LambdaFunction, LambdaVersion
-from samtranslator.model.apigateway import ApiGatewayRestApi
-from samtranslator.model.apigateway import ApiGatewayDeployment
+from samtranslator.model.apigateway import ApiGatewayDeployment, ApiGatewayRestApi
 from samtranslator.model.apigateway import ApiGatewayStage
 from samtranslator.model.iam import IAMRole
+from samtranslator.model.packagetype import IMAGE, ZIP
 from samtranslator.model.sam_resources import SamFunction, SamApi, SamHttpApi
 
 
-class TestCodeUri(TestCase):
+class TestCodeUriandImageUri(TestCase):
     kwargs = {
         "intrinsics_resolver": IntrinsicsResolver({}),
         "event_resources": [],
@@ -24,6 +24,8 @@ class TestCodeUri(TestCase):
     def test_with_code_uri(self):
         function = SamFunction("foo")
         function.CodeUri = "s3://foobar/foo.zip"
+        function.Runtime = "foo"
+        function.Handler = "bar"
 
         cfnResources = function.to_cloudformation(**self.kwargs)
         generatedFunctionList = [x for x in cfnResources if isinstance(x, LambdaFunction)]
@@ -34,14 +36,62 @@ def test_with_code_uri(self):
     def test_with_zip_file(self):
         function = SamFunction("foo")
         function.InlineCode = "hello world"
+        function.Runtime = "foo"
+        function.Handler = "bar"
 
         cfnResources = function.to_cloudformation(**self.kwargs)
         generatedFunctionList = [x for x in cfnResources if isinstance(x, LambdaFunction)]
         self.assertEqual(generatedFunctionList.__len__(), 1)
         self.assertEqual(generatedFunctionList[0].Code, {"ZipFile": "hello world"})
 
-    def test_with_no_code_uri_or_zipfile(self):
+    @patch("boto3.session.Session.region_name", "ap-southeast-1")
+    def test_with_no_code_uri_or_zipfile_or_no_image_uri(self):
+        function = SamFunction("foo")
+        with pytest.raises(InvalidResourceException):
+            function.to_cloudformation(**self.kwargs)
+
+    @patch("boto3.session.Session.region_name", "ap-southeast-1")
+    def test_with_image_uri(self):
+        function = SamFunction("foo")
+        function.ImageUri = "123456789.dkr.ecr.us-east-1.amazonaws.com/myimage:latest"
+        function.PackageType = IMAGE
+        cfnResources = function.to_cloudformation(**self.kwargs)
+        generatedFunctionList = [x for x in cfnResources if isinstance(x, LambdaFunction)]
+        self.assertEqual(generatedFunctionList.__len__(), 1)
+        self.assertEqual(generatedFunctionList[0].Code, {"ImageUri": function.ImageUri})
+
+    @patch("boto3.session.Session.region_name", "ap-southeast-1")
+    def test_with_image_uri_layers_runtime_handler(self):
+        function = SamFunction("foo")
+        function.ImageUri = "123456789.dkr.ecr.us-east-1.amazonaws.com/myimage:latest"
+        function.Layers = ["Layer1"]
+        function.Runtime = "foo"
+        function.Handler = "bar"
+        function.PackageType = IMAGE
+        with pytest.raises(InvalidResourceException):
+            function.to_cloudformation(**self.kwargs)
+
+    @patch("boto3.session.Session.region_name", "ap-southeast-1")
+    def test_with_image_uri_package_type_zip(self):
+        function = SamFunction("foo")
+        function.ImageUri = "123456789.dkr.ecr.us-east-1.amazonaws.com/myimage:latest"
+        function.PackageType = ZIP
+        with pytest.raises(InvalidResourceException):
+            function.to_cloudformation(**self.kwargs)
+
+    @patch("boto3.session.Session.region_name", "ap-southeast-1")
+    def test_with_image_uri_invalid_package_type(self):
         function = SamFunction("foo")
+        function.ImageUri = "123456789.dkr.ecr.us-east-1.amazonaws.com/myimage:latest"
+        function.PackageType = "fake"
+        with pytest.raises(InvalidResourceException):
+            function.to_cloudformation(**self.kwargs)
+
+    @patch("boto3.session.Session.region_name", "ap-southeast-1")
+    def test_with_image_uri_and_code_uri(self):
+        function = SamFunction("foo")
+        function.ImageUri = "123456789.dkr.ecr.us-east-1.amazonaws.com/myimage:latest"
+        function.CodeUri = "s3://foobar/foo.zip"
         with pytest.raises(InvalidResourceException):
             function.to_cloudformation(**self.kwargs)
 
@@ -57,6 +107,8 @@ class TestAssumeRolePolicyDocument(TestCase):
     def test_with_assume_role_policy_document(self):
         function = SamFunction("foo")
         function.CodeUri = "s3://foobar/foo.zip"
+        function.Runtime = "foo"
+        function.Handler = "bar"
 
         assume_role_policy_document = {
             "Version": "2012-10-17",
@@ -79,6 +131,8 @@ def test_with_assume_role_policy_document(self):
     def test_without_assume_role_policy_document(self):
         function = SamFunction("foo")
         function.CodeUri = "s3://foobar/foo.zip"
+        function.Runtime = "foo"
+        function.Handler = "bar"
 
         assume_role_policy_document = {
             "Version": "2012-10-17",
@@ -104,6 +158,8 @@ def test_with_version_description(self):
         function = SamFunction("foo")
         test_description = "foobar"
 
+        function.Runtime = "foo"
+        function.Handler = "bar"
         function.CodeUri = "s3://foobar/foo.zip"
         function.VersionDescription = test_description
         function.AutoPublishAlias = "live"