5. Using Aliases - epam/aws-syndicate GitHub Wiki

The deployment framework can work with static and dynamic aliases for referencing deployed resources.

Each alias type usage details are given further in this section.

The aliases are used for reference the alias value in the resources configuration.

An alias can be used to pass the resource name to the lambda function environment variable, it is very useful in case of extended prefix mode in the project because of automatic resource name resolving.

The aliases are stored in the file syndicate_aliases.yml inside the project configuration directory.

Access to the alias value by the name using the next syntax "${alias_name}"

Usage examples

#1: To configure the lambda function log expiration period via syndicate alias

• set up an alias by adding a key-value pair to the file syndicate_aliases.yml

	logs_expiration: 30

• Refer to the alias by name in the file lambda_config.json

	{
	  "version": "1.0",
	  "name": "demo",
	  "func_name": "handler.lambda_handler",
	  "resource_type": "lambda",
	  "iam_role_name": "demo-role",
	  "runtime": "python3.10",
	  "memory": 128,
	  "timeout": 100,
	  "lambda_path": "lambdas\\demo",
	  "dependencies": [],
	  "event_sources": [],
	  "env_variables": {},
	  "publish_version": false,
	  "url_config": {},
	  "ephemeral_storage": 512,
	  "logs_expiration": "${logs_expiration}",
	  "layers": []
	}

#2: To configure the dynamodb table name via syndicate aliases and set up it as a lambda function environment variable

• set up an alias by adding a key-value pair to the file syndicate_aliases.yml

	demo_table: Demo-table

• Refer to the alias by name in the file deployment_resources.json to set the table name via the alias

	{
		"${demo_table}": {
		"resource_type": "dynamodb_table",
		"hash_key_name": "id",
		"hash_key_type": "N",
		"read_capacity": 1,
		"write_capacity": 1,
		"global_indexes": [
		  {
			"name": "number-index",
			"index_key_name": "number",
			"index_key_type": "N"
		  }
		],
		"autoscaling": []
	  }
	}

• Refer to the alias by name in the file lambda_config.json to set up the lambda function environment variable with the table name.

Pay attention that the table name will be with the prefix and/or the suffix if prefixes and/or suffixes are configured in the project and extended prefix mode is enabled.

During the deployment, the environment variable with the name 'demo_table_name' that contains the actual dynamodb table name will be set in the lambda function environment.

	{
	  "version": "1.0",
	  "name": "demo",
	  "func_name": "handler.lambda_handler",
	  "resource_type": "lambda",
	  "iam_role_name": "demo-role",
	  "runtime": "python3.10",
	  "memory": 128,
	  "timeout": 100,
	  "lambda_path": "lambdas\\demo",
	  "dependencies": [],
	  "event_sources": [],
	  "env_variables": {
		"demo_table_name": "${demo_table}"
	  },
	  "publish_version": false,
	  "url_config": {},
	  "ephemeral_storage": 512,
	  "layers": []
	}

#1. To configure the lambda function log expiration period via syndicate alias:

• set up a static alias by adding a key-value pair to the file syndicate_aliases.yml

	logs_expiration: 30

• refer to the static alias by predefined enum value in the @LambdaHandler annotation

	@LambdaHandler(
        logsExpiration = RetentionSetting.SYNDICATE_ALIASES_SPECIFIED,
        ...
	)

#2. Configure the region and the bucket name via static aliases and set them up as a lambda function environment variables:

• set up a static alias by adding a key-value pairs into the file syndicate_aliases.yml

	region: eu-central-1
	notification_bucket: demo-example-notification-bucket

• refer to the static alias by name in the file deployment_resources.json to set the bucket name via the static alias

	{
	  ${notification_bucket}": {
		"resource_type": "s3_bucket"
	  }
	}

• refer to the aliases by names in the @EnvironmentVariable annotation:

	@EnvironmentVariables(value = {
        @EnvironmentVariable(key = "region", value = "${region}"),
        @EnvironmentVariable(key = "notification_bucket", value = "${notification_bucket}")
	})

• see full example at AWS-syndicate GitHub

Resource aliases enable automatic resource name resolution with prefix and suffix handling within AWS Syndicate configurations. This feature simplifies resource referencing across different deployment environments while maintaining naming consistency. By default, AWS Syndicate automatically applies configured prefixes and suffixes to resource names when they are referenced directly in meta descriptions. This behavior works for both resource names and ARNs without requiring special syntax:

// deployment_resources.json
{
  "MyTableName": {
    "resource_type": "dynamodb_table",
    "hash_key_name": "id",
    "hash_key_type": "N"
  }
}

// lambda_config.json
{
  ...
      "env_variables": {
        "table_name": "MyTableName", // Automatically resolved to include prefix/suffix and will be like "dev-MyTableName-prod"
        "table_arn": "arn:aws:dynamodb:us-east-1:123456789012:table/MyTableName" // Automatically resolved and will be like "arn:aws:dynamodb:us-east-1:123456789012:table/dev-MyTableName-prod"
      },
  ...
}

When referencing resources within text strings or complex expressions, use the resource name syntax: $rn{resource_name}, where $rn is the resource name identifier and {resource_name} is the actual resource name as defined in your configuration. This will help AWS Syndicate understand how to process this substring - as a mention of the previously described resource or simply as a string.

Basic resource reference in environment variables:

{
    "env_variables": {
        "table_name": "Table name is $rn{MyTableName}."
    }
}

Combining static aliases with resource aliases:

{
    "env_variables": {
        "table_name": "Table name is $rn{${table_name}}."
    }
}

In this example, ${table_name} (static alias) is resolved first, then $rn{...} (resource alias) is applied to the resolved static alias value.

Resource aliases automatically inherit the prefix and suffix configurations defined in your project settings, ensuring consistent naming across different deployment environments (development, staging, production) without manual configuration changes. This provides automatic resource name resolution, environment-specific naming consistency, simplified cross-environment deployments, and reduced configuration maintenance.

WARNING

1. Dynamic aliases are supported in all runtimes except Java.
2. Dynamic aliases are only applicable within trusted relationships in IAM roles and policy content in IAM policies.
3. Only API Gateway and Cognito resource IDs can be dynamically extracted using dynamic aliases.

Dynamic aliases are used when you need to reference the IDs of resources after those resources have been deployed.

A dynamic alias is set within the meta description of the AWS resource that influences the alias value. Currently, dynamic aliases are supported for two types of resources. For each resource type, you need to provide specific details:

IAM Policy alias:

• Action: apply_type: iam_policy
• Dependency name
• Policy Content

{
    // ...,
    "apply_changes": [
      {
        "apply_type": "iam_policy",
        "dependency_name": "YOUR_POLICY_NAME",
        "policy_content": {
          // ...
        }
      }
    ]
}

IAM Role alias:

• Action: apply_type: iam_role
• Dependency name
• Trusted relationships

{
    // ...,
    "apply_changes": [
      {
        "apply_type": "iam_role",
        "dependency_name": "YOUR_ROLE_NAME",
        "trusted_relationships": {
          // ...
        }
      }
    ]
}

The resource name in a dynamic alias is specified as #{resource_name}. For API Gateway and Cognito, this value is automatically replaced with the resource ID generated by AWS during deployment.

Example:

Suppose you have an IAM role (myRole) and an API Gateway (myApi) defined in deployment_resources.json. After the API Gateway is deployed, you need to update the role's trusted relationships by adding the API Gateway ID, which is only available after deployment. To achieve this, specify the apply_changes attribute in the API Gateway description. This attribute links the changes to the target role:

{
  "myRole": {
    "resource_type": "iam_role",
    "trusted_relationships": {
      "Version": "2012-10-17",
      "Statement": [
        {
          "Effect": "Allow",
          "Principal": {
            "Service": "apigateway.amazonaws.com"
          },
          "Action": "sts:AssumeRole",
          "Condition": {
            "StringEquals": {
              "aws:SourceArn": "#{myApi}"
            }
          }
        }
      ]
    },
    "predefined_policies": ["AWSLambdaSQSQueueExecutionRole"]
  },
  "myApi": {
    "resource_type": "api_gateway",
    "deploy_stage": "api",
    "resources": {
      "/test": {
        "enable_cors": {
          "state": true,
          "custom_headers": [],
          "custom_methods": [],
          "custom_origins": []
        },
        "ANY": {
          "authorization_type": "NONE",
          "integration_type": "mock",
          "default_error_pattern": true
        },
        "POST": {
          "authorization_type": "NONE",
          "integration_type": "mock",
          "default_error_pattern": true
        }
      }
    },
    "apply_changes": [
      {
        "apply_type": "iam_role",
        "dependency_name": "myRole",
        "trusted_relationships": {
          "Version": "2012-10-17",
          "Statement": [
            {
              "Effect": "Allow",
              "Principal": {
                "Service": "apigateway.amazonaws.com"
              },
              "Action": "sts:AssumeRole",
              "Condition": {
                "StringEquals": {
                  "aws:SourceArn": "#{myApi}"
                }
              }
            }
          ]
        }
      }
    ]
  }
}

LEGACY

Legacy

Note: This section (5.4 Static Aliases) is considered outdated. For current standards, refer to updated section.

The static aliases can be used for convenient distinction of infrastructures that are deployed from the same meta descriptions but need to have different resource naming in AWS.

For example, this can be used in setting up similar prod and dev environments, or deploying infrastructure in different regions or accounts.

The static aliases are described in the sdct_aliases.conf file which must be placed in the same directory with the sdct.conf file.

The sdct_aliases.conf includes the key-value list of aliases, for example:

dev_notification_bucket=notification-temp

During the deployment, the name, specified in the meta description as ${dev_notification_bucket} will be replaced with ‘notification-temp’.