Getting Started

Here you will find detailed information on how to get started with Attini. To find more guides and examples, please visit our guides section on our website.

Subsections of Getting Started

Install the Attini CLI

Installation time: ca 1 minute

Prerequisites

The Attini CLI depends on:

  1. The AWS CLI (If you are using AWS SSO you need AWS CLI version 2).
  2. Configured AWS CLI credentials.

Installation the Attini CLI

/bin/bash -c "$(curl -fsSL https://docs.attini.io/blob/attini-cli/install-cli.sh)"

Get started by running:

attini --help

To install the Attini Framework using the CLI, see install the Attini Framework.

Installation options

To use some of our installation options, you need to download the script and apply the desired flags:

curl -fsSO https://docs.attini.io/blob/attini-cli/install-cli.sh
chmod +x install-cli.sh
./install-cli.sh # [ -t installation target directory ] [ -v attini cli version ] [ -s silent ] [ -n no hints ]  [ -d debug ]

After the installation, it’s safe to delete the installation script (rm install-cli.sh)

-t

Type: String

The directory to which the script will save the Attini CLI.

This directory should be on you system PATH.

If this flag is omitted, the script will check if:

  • You are NOT acting as root.
  • The directory $HOME/bin exists.
  • The directory $HOME/bin is on you system PATH.

If all of the above is true, the script will save the Attini CLI to $HOME/bin, if not, the Attini CLI will be saved to /usr/local/bin which requires privileged access (root/admin).

Required: No

Default: $HOME/bin || /usr/local/bin

-v

Type: String

The version of the Attini CLI. Find available versions with the API, or in our Change log.

Required: No

Default: latest

-s

Silent; do not print download progress bar or info logging.

Required: No

Default: false

-n

No hints; do not print hints.

Required: No

Default: false

-d

Debug, will set x flag in the script for debugging.

Required: No

Default: false

Example
# Download and make executable
curl -fsSO https://docs.attini.io/blob/attini-cli/install-cli.sh
chmod +x install-cli.sh

# Install Attini CLI in $HOME/exe, with the latest version, and don't print logging and hints
./install-cli.sh -t "$HOME/exe" -v "latest" -s

# Clean up the script
rm -f install-cli.sh

Setup Attini CLI autocomplete

After you installed the Attini CLI, you can activate autocomplete by running this command:

source <(attini generate-completion)

If you have any issues with this command, see our common issues section.

To automatically run this command in new shells do the following:

RC_FILE=~/."${SHELL##*/}"rc;
echo "Adding attini auto complete to $RC_FILE"
echo 'source <(attini generate-completion)' >> $RC_FILE;
Note

If you are using zsh you might get this warning:

zsh compinit: insecure directories, run compaudit for list.
Ignore insecure directories and continue [y] or abort compinit [n]?

Fix this with this script:

compaudit | xargs chmod go-w

This command limits the access to some system files that zsh warns you about. We recommend that you do your own research regarding this issue or talk to your company’s systems administrators for approval before applying this fix.

Trouble shot the installation

If the Attini CLI is not working, please follow these steps:

  1. See if you can find the error in our common issues section.
  2. Run uname -m and uname -s in your terminal and verify that your computer is supported by the Attini CLI, see supported platforms.
  3. If your computer should be supported but is still having issue, please report this to support@attini.io.
  4. If your computer is not supported, please send a feature request to us on support@attini.io.

Windows installation

The Attini CLI does not currently support Windows. We recommend Windows users to use Windows Subsystem for Linux then follow the Linux installation guide. Running Linux on a virtual machine ex, virtualbox is also a viable option.

Manual installation

The Attini CLI is a pre-compiled executable available at:

https://docs.attini.io/api/v1/cli/get-cli/$(uname -m)/$(uname -s)/latest

The uname -m represent your current CPU architecture.

The uname -s represent your current operating system.

Find more information about supported CPU architectures and operating systems here.

latest represents the Attini CLI version, you can find more information about the available versions using our CLI API CLI change log.

To install the Attini CLI, you have to:

  1. Download the CLI.
  2. Put it in a directory on your system path.

Verify the installation

Verify the installation by running:

attini --version

Uninstall the Attini CLI

To uninstall the Attini CLI you just need to delete the attini file.

rm $(command -v attini)

If you have enabled Attini CLI autocomplete, you should remove the line source <(attini generate-completion) from your startup file (~/.bashrc or ~/.zshrc).

Supported operating systems and CPU architectures

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

  • Linux running on x86_64 architecture
  • Linux running on aarch64/arm64 architecture
  • Darwin (Mac) running on x86_64 architecture
  • Darwin (Mac) running on aarch64/arm64 architecture (Requires Rosetta 2, find more information here).
Note

We plan to build support for more operating systems and CPU architectures. If you have any requirements please send an email to support@attini.io and we will try to prioritize accordingly.

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 CLI Information API

List the available operating systems and cpu architectures:

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

Get available Attini CLI versions:

curl https://docs.attini.io/api/v1/cli/get-cli-versions/{cpu_architecture}/{operating_systems}
Example
curl https://docs.attini.io/api/v1/cli/get-cli-versions/$(uname -m)/$(uname -s)
curl https://docs.attini.io/api/v1/cli/get-cli-versions/x86_64/Linux
curl https://docs.attini.io/api/v1/cli/get-cli-versions/x86_64/Darwin

Get re-routed to the Attini CLI location:

curl https://docs.attini.io/api/v1/cli/get-cli/{cpu_architecture}/{operating_systems}/{version}
Example
curl https://docs.attini.io/api/v1/cli/get-cli/$(uname -m)/$(uname -s)/latest
curl https://docs.attini.io/api/v1/cli/get-cli/x86_64/Linux/2.5.9
curl https://docs.attini.io/api/v1/cli/get-cli/x86_64/Darwin/2.5.8

Find additional info at our changelog.

Install the Attini Framework

Installation time: ca 4 minutes

For the Attini framework to function, you need to deploy the framework in your AWS Regions. This is done by creating a CloudFormation stack called attini-setup.

The underlying infrastructure for the Attini framework is essentially free if it’s not used, so you can onboard AWS Accounts and Regions without being concerned about cost.

Security information
  • We recommend you not use AWS Root user for this deployment, instead you should create an IAM Role or IAM User.
  • The DynamoDB tables created by the attini-setup are encrypted with the AWS-managed KMS keys.
  • The S3 Buckets created by the attini-setup are encrypted with S3 server side encryption (SSE-S3).
  • All API calls made by the Attini framework are secured with AWS IAM.

Installation and update

Using the Attini CLI

  1. Install the Attini CLI.
  2. Now run the Attini CLI command attini setup to deploy the Attini framework with the default configuration. If you run attini setup --guided you will find more information about the configuration options. You can also find more information about the configuration below.
Example command

The following command gives Attini very high permissions, so it’s only recommended for sandbox environments.

attini setup --give-admin-access --create-deployment-plan-default-role --create-init-deploy-default-role --accept-license-agreement
Note

You can always update the attini-setup CloudFormation stack with your own configurations after it has been created. You can do this via the Attini CLI command attini setup or in the AWS console (If you can’t see the CloudFormation stack attini-setup, please verify that you are in the correct AWS Region and Account).

Using the AWS console

  1. Create a CloudFormation stack using the template:

    https://attini-artifacts-{Region}.s3.amazonaws.com/attini-setup/latest/attini-setup.yaml

    Replace {Region} with your current region, ex us-east-1 or eu-west-1.

    If you want to install a specific version of Attini, replace “latest” in the URL with a specific version. Find more info about Attini versions here.

  2. The CloudFormation stack have to be named attini-setup

  3. Optional: Change the default configuration in the Parameter section, find more information in the configuration below.

Note

If you just want to download the attini-setup template, you can download it from any region ex: https://attini-artifacts-us-east-1.s3.amazonaws.com/attini-setup/latest/attini-setup.yaml

Configuration

Email

This email is only used to send operational information when needed.

Required: false

EnvironmentParameterName

The Attini framework can auto-configure certain CloudFormation parameters. If you want the Attini framework to automatically configure a CloudFormation parameter called ex “env”, “Environment” or “EnvironmentName” instead of “AttiniEnvironmentName”, you can change that here.

Required: false

Default: AttiniEnvironmentName

CreateInitDeployDefaultRole

Should Attini create a highly privileged default role for Attini init deploy? If this is false, you have to configure InitDeployRoleArn.

Required: false

Default: false

InitDeployRoleArn

Arn for the Attini init deploy.

This role needs the privileges to create all the resources for your Attini init deploys, which contains your Attini deployment plans.

See AttachLeastPrivilegePolicyToInitDeployRole configuration as well.

Required: If CreateInitDeployDefaultRole is true, then is required.

Default: empty sting

AttachLeastPrivilegePolicyToInitDeployRole

If InitDeployRoleArn is configured, should the attini-setup attach the least privilege policy to that IAM Role?

If you configure this to be false, you need to give InitDeployRole sufficient permissions. Otherwise, there is a risk that deployments freeze without proper error messages.

Find the current least privilege policy in the attini-setup template under the name AttiniInitDeploymentPolicy.

Note

The main reason to set this to false is if you want to use the same IAM Role for the init deploy in multiple regions. If this is true and you use the same IAM role for the init deploy the attini-setup stack will fail with the error "Maximum policy size of 10240 bytes exceeded for role". This is because multiple attini-setup stacks attach the least privilege policy to the same role.

Required: false

Default: true

CreateDeploymentPlanDefaultRole

Should Attini create a default Service role for the Attini DeploymentPlans underlying AWS StepFunctions?

The default role has the permission to trigger/run/execute/publish/put on any AWS Lambda, AWS StepFunction, ECS task, CodeBuild project, SNS topic, or SQS queue in your AWS Account.

Note

If this is false, you will have to configure an RoleArn for every Attini DeploymentPlan you create.

Required: false

Default: true

GiveAdminAccess

Give the Attini framework admin access.

This will create two admin roles, one for the Attini runner and one for the Attini action Lambda function, which runs Attini steps like AttiniCfn or AttiniSam.

These roles will be used unless another role is specified.

If this is false, you need to provide adequate permissions to the different Attini functions via their IAM configuration options, such as the RoleArn, StackRoleArn or ExecutionRoleArn attributes.

Warning

If this is true, Attini steps like AttiniRunnerJobs, AttiniCfn, AttiniCdk and AttiniSam will get AdministratorAccess by default.

Required: false

Default: false

UseAdministratorAccessForDeployingCloudformation

This parameter is deprecated. See GiveAdminAccess instead.

Required: false

Default: false

VpcId

If you require the Attini Lambda functions to be executed in any specific VPC, please specify it here. This also requires SubnetsIds to be configured.

This has to be a valid VPC id in your current region or the value “AwsManagedNetwork”.

Required: false

Default: AwsManagedNetwork

SubnetsIds

If you require the Attini Lambda functions to be executed in any specific subnets, please specify it here. This also requires VpcId to be configured.

This has to be a comma-separated list of private subnets ids in the VPC you specify in the VpcId, or the value "AwsManagedNetwork".

Required: false

Default: AwsManagedNetwork

AwsServiceRolesContainsString

This parameter helps you control which CloudFormation Stack roles can be used by the Attini framework. This means that an IAM Role configured in the StackRoleArn in the Attini deployment plan will need to have this string in the IAM Roles name or path.

If this parameter is * then Attini will be able to do iam:PassRole to any IAM Role in your AWS Account.

This parameter becomes irrelevant if you configure ExecutionRoleArn, because then the iam:PassRole permission will be configured in the Execution Role.

Example

If this is configured to be attini, the IAM Role name or path will need to have attini somewhere in it, like arn:aws:iam::{AccountId}:role/attini-my-cloudformation-stack-role or arn:aws:iam::{AccountId}:role/attini/my-cloudformation-stack-role.

Required: false

Default: attini

CodeSigningProfileArn

What code signing profile should Attini Lambda function code be signed with?

If you deploy to a region where AWS Signer is available, the default will be to use “Attini code signing profile”, and the CodeSigningPolicies.UntrustedArtifactOnDeployment configuration will be set to “Enforce”.

Required: false

Default: "no-code-signing" or "Attini code signing profile"

ResourceAllocation

If you are running a lot of other AWS Lambda functions in your account, it’s recommended to use the reserved concurrency. To make sure that your different workloads can't interfere with each other. You can reserve concurrency for the Attini Lambda functions by configuring this parameter.

Dynamic will disable reserved concurrency for the Attini Lambda functions.

Small will reserve 15 AWS Lambda concurrency for the Attini functions. ́ Medium will reserve 30 AWS Lambda concurrency for the Attini functions.

Large will reserve 69 AWS Lambda concurrency for the Attini functions.

Required: false

Default: Dynamic

RetainDistributionDays

Specify how many distributions should be retained, specify 0 to retain all forever. Find more information at Attini artifact life cycle.

Required: false

Default: 10

RetainDistributionVersions

Specify how many distributions should be retained, and specify 0 to retain all forever. Find more information at Attini artifact life cycle.

Required: false

Default: 10

AutoUpdate

Should Attini framework auto-update? If yes, enter a cron or rate expression or when it should be done. If you don’t want to auto-update, leave this field empty. More info about cron or rate expressions

Required: false

Default: empty sting

LogLevel

Log level for all Attini Lambdas, INFO is recommended. A higher LogLevel (ex WARN) will save CloudWatch cost. A lower LogLevel (ex DEBUG) might help to troubleshoot but will incur extra CloudWatch costs.

Required: false

Default: INFO

LicenseToken

LicenseToken is used to associate your Attini usage with a support agreement. Create a token in the Attini admin portal.

Required: false

Default: no-support-agreement

AcceptLicenseAgreement

Accept the Attini license agreement. Find more information in our Product offering.

Required: true

Default: false

Deleting/Clean up the Attini framework

Warning

All deployment history and Attini features will be lost if you do this.

If you no longer want to use the Attini Framework, you can delete it from your AWS region using these steps:

  1. Empty the s3 bucket attini-deployment-origin-${Region}-${AccountId}
  2. Empty the s3 bucket attini-artifact-store-${Region}-${AccountId}
  3. Delete the CloudFormation stack attini-setup
  4. Delete any parameters in AWS SSM Parameter store with the prefix /attini/

If you change your mind about using Attini, the framework can easily be installed again.


Content