Attini Runner¶

Attini::Deploy::Runner¶

Attini Runner is based on Amazon ECS and uses the ECS RunTask API call to start the runner.

The Attini::Deploy::Runner resource only works in conjunction with the Attini deployment plan. See AttiniRunnerJob for more information.

The Attini::Deploy::Runner can ONLY be created in the Attini init deploy stack.

The DeploymentPlan template requires the AttiniDeploymentPlan Transform configuration:

Type: Attini::Deploy::Runner
Properties:
  TaskDefinitionArn: String
  ContainerName: String
  EcsCluster: String
  RoleArn: String
  Image: String
  Memory: Integer
  Cpu: Integer
  Ec2Configuration:
    Ami: String
    InstanceType: String
    InstanceProfileName: String
  RunnerConfiguration:
    MaxConcurrentJobs: Number
    IdleTimeToLive: Number
    JobTimeout: Number
    LogLevel: String
  AwsVpcConfiguration:
    Subnets: String,String
    SecurityGroups: String,String
    AssignPublicIp: String
  Startup:
    Commands:
      - String
    CommandsTimeout: Number

TaskDefinitionArn

Type: String

ECS task definition that the Attini Runner should use.

Note

The container image ENTRYPOINT or ECS task definition Entrypoint, must NOT be configured. If the ENTRYPOINT is configured, it will cause the Attini Runner not to start properly.

Depending on the ENTRYPOINT content, it can cause zombie ECS tasks.

Container image CMD and ECS task definition Command will be overwritten by the RunTask API call that Attini will call on your behalf.

To run commands from the Attini Runner, use the Attini::Deploy::DeploymentPlan AttiniRunnerJob type.

If you want to use CloudFormation to define the task definition, see AWS::ECS::TaskDefinition for more information.

If TaskDefinitionArn is not configured, the default task definition will be used.

The Your TaskDefinitions IAM Role requires a basic execution policy called:

arn:aws:iam::${AccountId}:policy/attini-runner-basic-execution-policy-${Region}

The “TaskDefinitionArn” configuration can not be combined with the “Image” configuration.

If “TaskDefinitionArn” and “Image” is omitted, default runner will be used.

Required: No

Default: None

ContainerName

Type: String

The name of the container in the task definition. This is not mandatory if there is only one container definition in the specified task definition.

Required: No

Default: None

EcsCluster

Type: String

The name of the Attini Runners ECS Cluster. This is not mandatory if there is a default cluster in the account.

Note

If there is no default cluster, you can create one with the AWS CLI command aws ecs create-cluster (omit all flags).

Required: No

Default: attini-default

RoleArn

Type: String

This IAM Role will override the IAM Role from the TaskDefinition.

This IAM Role requires a basic execution policy that allows the runner to communicate with the deployment plan:

arn:aws:iam::${AccountId}:policy/attini-runner-basic-execution-policy-${Region}

CloudFormation example:

AttiniRunnerRole:
  Type: AWS::IAM::Role
  Properties:
    Description: Attini runner task role
    Path: /attini/
    AssumeRolePolicyDocument:
      Version: 2012-10-17
      Statement:
        -
          Effect: Allow
          Principal:
            Service: ecs-tasks.amazonaws.com
          Action: sts:AssumeRole
    ManagedPolicyArns:
      - !Sub arn:aws:iam::${AWS::AccountId}:policy/attini-runner-basic-execution-policy-${AWS::Region}

Required: No

Default: None

Image

Type: String

A Container image that the runner should use. If you configure this value, Attini will configure a TaskDefinition for you with the following configuration:

{RunnerName}TaskDefinition:
  Type: AWS::ECS::TaskDefinition
  Properties:
    ContainerDefinitions:
      - Name: Container
        Image: ${Image}
        LogConfiguration:
          LogDriver: awslogs
          Options:
            awslogs-group: !Ref {RunnerName}LogGroup
            awslogs-region: !Ref AWS::Region
            awslogs-stream-prefix: logs
    Cpu: 512
    ExecutionRoleArn: # Set to {RoleArn} or "Fn::Sub: arn:aws:iam::${AWS::AccountId}:role/attini/attini-default-runner-role-${AWS::Region}"
    TaskRoleArn: # Set to {RoleArn} or "Fn::Sub: arn:aws:iam::${AWS::AccountId}:role/attini/attini-default-runner-role-${AWS::Region}"
    Memory: 3072
    NetworkMode: awsvpc
    RequiresCompatibilities:
      - FARGATE


{RunnerName}LogGroup:
  Type: AWS::Logs::LogGroup
  Properties:
    RetentionInDays: 90

If you want to change any configuration, you can create your own task definition.

The “Image” configuration can not be combined with the “TaskDefinitionArn” configuration.

If “TaskDefinitionArn” and “Image” is omitted, default runner will be used.

Required: No

Default: None

Memory

Type: Integer

This configuration will override the memory configuration from the TaskDefinition.

If the runner uses Fargate, this has to be a valid Fargate CPU and memory configuration.

If the runner uses EC2, we recommend the memory configuration to be ca 70-80% of the available memory of the EC2 Host so that there is some memory left for the Host OS. Exactly how much memory your Host OS needs depends on your workload so you might need to adjust this if you face any issues.

Required: No

Default: None

Cpu

Type: Integer

This configuration will override the CPU configuration from the TaskDefinition.

If the runner uses Fargate, this has to be a valid Fargate CPU and memory configuration.

If the runner uses EC2, this value has to be smaller than the available Host CPU.

Required: No

Default: None

Ec2Configuration

Configuration for the runner EC2 Host.

If this EC2 configuration is set, the Attini runner will use ECS EC2 launch type, otherwise Fargate launch type will be used. Consequently, the task definition has to be compatible with the correct launch type.

Find more information in the reference architecture.

Required: No

Ami
Type: String

The Ami (Amazon Machine Image) has to be a valid AMI ID or one of the following values:

AmazonLinux2

AmazonLinux2_arm64

AmazonLinux2_gpu

AmazonLinux2_inf

AmazonLinux2023

AmazonLinux2023_arm64

AmazonLinux2023_inf

Attini will use a corresponding recommended AMI fetched from AWS SSM Parameter store to get the correct AMI ID for your region.

If you configure your own AMI ID, it needs the ECS agent installed and enabled.

Required: No

Default: AmazonLinux2

InstanceType
Type: String

AWS Instance type, for example m5.large.

Required: Yes

InstanceProfileName:
Type: String

Using an instance profile name you can give your EC2 custom IAM Access.

Required: No

Default: attini-runner-default-instance-profile-${AWS::Region} (created by attini-setup)

RunnerConfiguration

Configuration for the runner.

Required: No

MaxConcurrentJobs
Type: Number

The max amount of concurrent jobs the Attini Runner will execute.

Required: No

Default: 5

Allowed Range: 1-20

IdleTimeToLive
Type: Number

The number of seconds the Attini Runner will stay alive without any jobs executing. New jobs will reset the countdown.

Required: No

Default: 3600

Allowed Range: 60-86400

JobTimeout
Type: Number

The number of seconds a job can execute before the Attini Runner aborts the execution.

Required: No

Default: 3600

Allowed Range: 5-172800

LogLevel
Type: String

The log level of the Attini Runner.

Required: No

Default: INFO

Allowed Values: DEBUG | INFO | WARN | ERROR | OFF | ALL

AwsVpcConfiguration

The VPC configuration for the ECS task.

Note

If AwsVpcConfiguration is omitted, Attini will use the default VPC and create a new security group resource in the init deploy stack. The security group will have no inbound rules (no openings), but allow all outgoing traffic.

Required: No

AwsVpcConfiguration Subnets
Type: Comma-separated String

A comma-separated list of the subnet ids associated with the ECS task. For more information see the AWS ECS VPC documentation

Required: Yes

Default: None

AwsVpcConfiguration SecurityGroups
Type: Comma-separated String

A comma-separated list of the security group ids associated with the ECS task. For more information see the AWS ECS VPC documentation

Required: No

Default: None

AwsVpcConfiguration AssignPublicIp
Type: String

For more information, see the AWS ECS VPC documentation.

Required: Yes

Default: None

Allowed Values: ENABLED | DISABLED

Startup

Startup instructions for the Attini Runner.

Required: No

Startup Commands
Type: List<String>

List of shell commands that runs when the Attini Runner starts.

Required: No

Default: None

Startup CommandsTimeout
Type: Number`

The number of seconds the startup commands can execute before the Attini Runner aborts the execution.

Required: No

Default: 3600

Allowed Range: 5-172800

Environment variables¶

You can configure any environment variables you need on the Attini Runner via the image build process (ex Dockerfile) or using the ECS task definition.

However, the Attini framework will automatically populate these environment variables:

ATTINI_ENVIRONMENT_NAME: The environment from the payload
ATTINI_DISTRIBUTION_NAME: The distributionName from the payload
ATTINI_DISTRIBUTION_ID: The distributionId from the payload
ATTINI_ARTIFACT_STORE: The deploymentSource.deploymentSourceBucket from the payload
ATTINI_DISTRIBUTION_ARTIFACTS_PREFIX: The deploymentSource.deploymentSourcePrefix from the payload
ATTINI_INPUT: The location of a JSON file that contains the input payload. Find more information here.
ATTINI_OUTPUT: The location of a JSON file that the Attini Runner will pass as output to the payload. Find more information here.
ATTINI_SOURCE_DIR: The working directory from where the AttiniRunnerJob is executed. This directory will also contain all the original files from the Attini distribution.
ATTINI_STEP_NAME: The name of the deployment plan step name.
ATTINI_AWS_ACCOUNT: The current AWS Account.
ATTINI_AWS_REGION: The current AWS Region.

Payload input and output¶

Input

Within the Attini Runner job, you can access the deployment plan payload input via a JSON file available on the runner. The path to the JSON file is available to the job commands via the ATTINI_INPUT environment variable.

Output

If you want later steps in the deployment plan to access information from your job, you can save that data to a file on the runner. That file path is available through the ATTINI_OUTPUT environment variable.

The contents of the output file will be passed to the deployment plan payload under the path output.[StepName]. If the contents are valid JSON it will be passed as it is. If the contents are not valid JSON it will be converted to a JSON object with the contents being present under the “result” field, for example {"result": "my-none-json-value"}.

Hint: jq is a good tool when you work with JSON using bash.

Example

StepName:
  Type: AttiniRunnerJob
  Properties:
    Runner: HelloWorldRunner
    Commands:
      - cat ${ATTINI_INPUT} # This will print the input as a string.
      - echo '{"MyKey":"MyValue"}' > ${ATTINI_OUTPUT} # This will add the JSON object to the output

Install the Attini Runner¶

The Attini Runner will automatically be installed at boot if it’s not installed. However, it is recommended to install it on your own build image. This will decrease startup time, give you better control over software versions and reduce the risk of other failures. Installing the Attini Runner at boot also required internet access.

We recommend you configure a Linux user for security reasons. If you pre-install all the software your deployment needs, the use-cases for running jobs as root decrease significantly.

Example Dockerfile¶

Note

For the below dockerfile to work, you need to authenticate with the Amazon ECR public registries using the command:

aws ecr-public get-login-password --region us-east-1 | docker login --username AWS --password-stdin public.ecr.aws

# Define the base image and update all software
FROM public.ecr.aws/amazonlinux/amazonlinux:latest
RUN yum update -y && yum clean all

# Install the attini-runner
RUN curl -sfL#o /usr/local/bin/attini-runner https://docs.attini.io/api/v1/runner/get-runner/$(uname -m)/$(uname -s)/latest; chmod +x /usr/local/bin/attini-runner

# Configure a user (recommended)
RUN yum install -y shadow-utils && yum clean all && useradd attini
USER attini

Limitations¶

CloudFormation intrinsic functions¶

Some parts of the Attini::Deploy::Runner configuration will be moved into the deployment plan state language definition so that it can be used by when Attini runs the RunTask API Call. This means that some CloudFormation functions (ex Fn::Join or Fn::ImportValue) might not work as expected. As a workaround, your can use deployment plan definition substitutions and reference the substitutions in the Attini::Deploy::Runner.

Amazon ECS service quotas¶

The Attini Runner is running as an ECS Fargate Task, which means that all Amazon ECS limitations also apply to the Attini Runner.

Supported operating systems and CPU architectures¶

The Attini Runner works on the following operating systems and CPU architectures:

Linux running on x86_64 architecture
Linux running on aarch64/arm64 architecture

Note

If you need support for other operating systems or CPU architectures please send an email to support@attini.io and we will try to accommodate the request.

You can find your operating system and CPU architecture by running uname -s and uname -m in a terminal. Please include this information in the support email.

Attini Runner information API¶

List the available operating systems and CPU architectures¶

curl https://docs.attini.io/api/v1/runner/get-supported-platforms

Get available Attini Runner versions¶

curl https://docs.attini.io/api/v1/runner/get-runner-versions/{cpu_architecture}/{operating_systems}

Examples

curl https://docs.attini.io/api/v1/runner/get-runner-versions/$(uname -m)/Linux
curl https://docs.attini.io/api/v1/runner/get-runner-versions/x86_64/Linux
curl https://docs.attini.io/api/v1/runner/get-runner-versions/aarch64/Linux

Get re-routed to the Attini Runner location¶

curl https://docs.attini.io/api/v1/runner/get-runner/{cpu_architecture}/{operating_systems}/{version}

Examples

curl https://docs.attini.io/api/v1/runner/get-runner/$(uname -m)/Linux/latest
curl https://docs.attini.io/api/v1/runner/get-runner/x86_64/Linux/1.0.0
curl https://docs.attini.io/api/v1/runner/get-runner/aarch64/Linux/1.0.0