Configure and deploy your first Attini project

Getting started

An Attini project is a directory that contain the following files:

  1. (Required) The first file is the “attini-config” (attini-config.yaml, attini-config.yml or attini-config.json).

  2. (Optional) The second file is the Init deploy template (CloudFormation template) which contains the Attini deployment plan.

  3. (Optional) Any files that you need for your IT environment (ex templates, configuration files, code/scrips files, website content, playbooks/recipes etc).

You can automatically generate a minimal attini-config file and Init deploy template with the following command (you have to stand in the root of your project):

attini init-project skeleton

When the Attini project (directory) is zipped (see attini package CLI command), it becomes a Attini distribution.

For the rest of this page we will go through the content of the “attini-config” and the “Init deploy template” (Attini deployment plan) and how it can be deployed.


attini-config

Find detailed information in the API reference

In the root of your project there will be a file called attini-config.yaml (if you ran the attini init-project skeleton command) that looks like this.

distributionName: skeleton
initDeployConfig:
  template: /deployment-plan.yaml
  stackName: ${environment}-${distributionName}-init-deployment
  parameters:
    default:
      parameterKey: parameterValue
    environmentName:
      parameterKey: parameterValue


package: # When you use the Attini CLI to "package" a distribution, these instructions will be used, find more info here https://docs.attini.io/api-reference/attini-configuration.html
  prePackage:
    commands: # These shell commands will be executed on a temporary copy of your files so they will not effect your source files
      - echo "Setting the distribution id to random"
      - attini configure set-dist-id --random
        # Using the Attini CLI to set the distribution id, if you use the "--id" flag instead of random you can set this to any value you want
        # We recommend you to use something that can be linked to your source control, example a git commit
  • distributionName is the most important value, it makes sure the Attini Framework can separate between our different projects.

  • initDeployConfig is used to configure the Init deploy stack which contains the Attini deployment plan.

  • package is used to automate anything you need before the project is packaged into an Attini distribution. You can for example do the following.

    • Set the distribution id (see Attini CLI command attini configure set-dist-id).

    • Get files or configuration from external sources (ex standard templates, software versions etc).

    • Synthesize CDK projects.


Init deploy template containing a deployment plan

Find detailed information:

Transform

Open the file /deployment-plan.yaml that was generated by the skeleton command and look at the Transform section.

Transform:
- AttiniDeploymentPlan
- AWS::Serverless-2016-10-31

Theses Transform (CloudFormation macros) converts the Attini::Deploy::DeploymentPlan resource into a collection of AWS resources that makes the Attini workflow possible (AttiniDeploymentPlan is dependent on AWS::Serverless-2016-10-31 macro).

Note

The init deploy stack does not need a deployment plan, it can be just an plain CloudFormation or SAM template.

Parameters

Parameters:
  AttiniEnvironmentName:
    Type: String

  ParameterKey:
    Type: String
  • The AttiniEnvironmentName is automatically populated by Framework Parameters.

    Note

    The name “AttiniEnvironmentName” can be re-mapped when you install the Attini Framework, so if you want it to be called ex “EnvironmentName”, “Environment” or “Env” its easy to set up.

  • ParameterKey value comes from the attini-config file.

Resources

Now look at the Resources section.

Resources:
  DeploymentPlan:
    Type: Attini::Deploy::DeploymentPlan # https://docs.attini.io/api-reference/deployment-plan.html
    Properties:
      DeploymentPlan:
        StartAt: Step1 # https://docs.aws.amazon.com/step-functions/latest/dg/concepts-amazon-states-language.html
        States:
          Step1:
            Type: AttiniCfn # https://docs.attini.io/api-reference/deployment-plan-types.html
            Properties:
              StackName: StackName # fill in your Cloudformation stack name
              Template: /Template.yaml
              # ExecutionRoleArn: Its recommended to use ExecutionRole or StackRole to create a "least privileged" deployment.
              # Find more information here https://docs.attini.io/architecture/securing-the-framework.html#executionrole
              Parameters:
                ParameterValue: !Ref ParameterValue
            End: True

It only contains 1 resource now, but you can add AWS CloudFormation resources or AWS SAM Resources you need.

Now reconfigure Step1 to use one of your own templates, then run these Attini CLI Commands:

attini context # Just to make sure that you are logged in to the right AWS account and region (Your AWS CLI Credentials are used).
attini environment create dev # This will register a environment called "dev" in this AWS account and region.
attini deploy run .

Now the following will happen:

  1. The Attini CLI will package your files into a Attini distribution (see that a zip file was created in you project folder).

  2. The Attini CLI will upload the Attini distribution into to the Attini Framework in your current AWS account and region.

  3. The Attini Framework will create/update the Init deploy CloudFormation stack.

  4. When the Init deploy CloudFormation stack is finished, the Attini Framework will trigger the Deployment Plan.


Example deployment plan template

AWSTemplateFormatVersion: "2010-09-09"
Transform:
  - AttiniDeploymentPlan
  - AWS::Serverless-2016-10-31

Parameters:
  AttiniEnvironmentName:
    Type: String

Resources:
  SimpleDeploymentPlan:
    Type: Attini::Deploy::DeploymentPlan
    Properties:
      DeploymentPlan:
        StartAt: DeployVpc
        States:
          DeployVpc:
            Type: AttiniCfn
            Properties:
              Template: /network/vpc.yaml
              StackName: vpc
              ConfigFile: !Sub /network/${AttiniEnvironmentName}-vpc.json
            End: true