Github Action: Deploy StackStorm

Action Summary

This action deploys a Stackstorm instance to an AWS VM (EC2) with Terraform and Ansible.

If you would like to deploy a backend app/service, check out our other actions:

Action	Purpose
Deploy Docker to EC2	Deploys a repo with a Dockerized application to a virtual machine (EC2) on AWS
Deploy React to GitHub Pages	Builds and deploys a React application to GitHub Pages.
Deploy static site to AWS (S3/CDN/R53)	Hosts a static site in AWS S3 with CloudFront

And more!, check our list of actions in the GitHub marketplace

Need help or have questions?

This project is supported by Bitovi, A DevOps consultancy.

You can get help or ask questions on our Discord channel! Come hang out with us; We love discussing solutions!

Or, you can hire us for training, consulting, or development. Set up a free consultation.

Prerequisites

• An AWS account and Access Keys
• The following secrets should be added to your GitHub actions secrets:
  • AWS_ACCESS_KEY_ID
  • AWS_SECRET_ACCESS_KEY
  • ST2_AUTH_USERNAME
  • ST2_AUTH_PASSWORD

⚠️ In the latest release, some variables were replaced. Old one will not work.

Old variable	Replaced By
aws_extra_tags	aws_additional_tags
aws_ec2_instance_profile	aws_ec2_iam_instance_profile
aws_ec2_instance_vol_size	aws_ec2_instance_root_vol_size
aws_domain_name	aws_r53_domain_name
aws_sub_domain_name	aws_r53_sub_domain_name
aws_root_domain_deploy	aws_r53_root_domain_deploy
aws_cert_arn	aws_r53_cert_arn
aws_create_root_cert	aws_r53_create_root_cert
aws_create_sub_cert	aws_r53_create_sub_cert
aws_no_cert	aws_r53_enable_cert ⚠️

⚠️ aws_no_cert has the opossite value of aws_r53_enable_cert. Cert lookup is set to true by default, and won't fail if it can't find any.

Example usage

Create a Github Action Workflow .github/workflow/deploy-st2.yaml with the following to build on push to the main branch.

# Deploy ST2 Single VM with GHA
name: CD

on:
  push:
    branches: [ main ]

jobs:
  deploy-st2:
    runs-on: ubuntu-latest
    steps:
    - id: deploy-st2
      name: Deploy StackStorm
      # NOTE: we recommend pinning to the latest numeric version
      # See: https://github.com/bitovi/github-actions-deploy-stackstorm/releases
      uses: bitovi/github-actions-deploy-stackstorm@v0.4.0
      with:
        aws_default_region: us-east-1
        aws_access_key_id: ${{ secrets.AWS_ACCESS_KEY_ID}}
        aws_secret_access_key: ${{ secrets.AWS_SECRET_ACCESS_KEY}}
        st2_auth_username: ${{ secrets.ST2_AUTH_USERNAME}}
        st2_auth_password: ${{ secrets.ST2_AUTH_PASSWORD}}
        st2_packs: "st2,aws,github"

This will create the following resources in AWS:

• An EC2 instance
• Route53 records
• A load balancer
• Security groups (ports 80, 443, 22)
• Optionally, use an existing or define a new VPC with subnets (see aws_create_vpc)

For more details about what is created, see operations/deployment/terraform/modules

Customizing

Inputs

1. Action Defaults
2. AWS Configuration
3. EC2
4. Stackstorm inputs
5. Stack Management
6. Domains and certificates
7. VPC
8. Advanced Options

Outputs

1. Action Outpus

The following inputs can be used as steps.with keys:

Action defaults Inputs

Name	Type	Description
checkout	Boolean	Set to false if the code is already checked out. (Default is true).

---

AWS Configuration Inputs

Name	Type	Description
aws_access_key_id	String	AWS access key ID
aws_secret_access_key	String	AWS secret access key
aws_session_token	String	AWS session token
aws_default_region	String	AWS default region. Defaults to us-east-1
aws_resource_identifier	String	Set to override the AWS resource identifier for the deployment. Defaults to ${GITHUB_ORG_NAME}-${GITHUB_REPO_NAME}-${GITHUB_BRANCH_NAME}.
aws_additional_tags	JSON	Add additional tags to the terraform default tags, any tags put here will be added to all provisioned resources.

---

EC2 Instance config

Name	Type	Description
aws_ec2_instance_type	String	The AWS IAM instance type to use. Default is t3.medium. See this list for reference.
aws_ec2_instance_root_vol_size	Integer	Define the volume size (in GiB) for the root volume on the AWS Instance. Defaults to 8.
aws_ec2_instance_root_vol_preserve	Boolean	Set this to true to avoid deletion of root volume on termination. Defaults to false.
aws_ec2_security_group_name	String	The name of the EC2 security group. Defaults to SG for ${aws_resource_identifier} - EC2.
aws_ec2_iam_instance_profile	String	The AWS IAM instance profile to use for the EC2 instance. Will create one if none provided with the name aws_resource_identifier.
aws_ec2_create_keypair_sm	Boolean	Generates and manages a secret manager entry that contains the public and private keys created for the ec2 instance. Defaults to false.
aws_ec2_instance_public_ip	Boolean	Add a public IP to the instance or not. Defaults to true.
aws_ec2_additional_tags	JSON	Add additional tags to the terraform default tags, any tags put here will be added to ec2 provisioned resources.

---

Stackstorm inputs

Name	Type	Description
st2_auth_username	String	Username used by StackStorm standalone authentication. Set as a secret in GH Actions.
st2_auth_password	String	Password used by StackStorm standalone authentication. Set as a secret in GH Actions.
st2_packs	String	Comma separated list of packs to install. If you modify this option, be sure to also include st2 in the list. Defaults to "st2"
st2_ansible_extra_vars_file	String	Relative path from project root to Ansible vars file. If you'd like to adjust more advanced configuration; st2 version, st2.conf, RBAC, chatops, auth, etc. See https://github.com/stackStorm/ansible-st2#variables for the full list of settings. The Ansible vars will take higher precedence over the GHA inputs.
st2_version_tag	String	Stackstorm Ansible release tag to use. See https://github.com/StackStorm/ansible-st2/releases

---

Stack Management

Name	Type	Description
tf_stack_destroy	Boolean	Set to true to destroy the stack - Will delete the elb logs bucket after the destroy action runs.
tf_state_file_name	String	Change this to be anything you want to. Carefull to be consistent here. A missing file could trigger recreation, or stepping over destruction of non-defined objects. Defaults to tf-state-aws.
tf_state_file_name_append	String	Appends a string to the tf-state-file. Setting this to unique will generate tf-state-aws-unique. (Can co-exist with tf_state_file_name)
tf_state_bucket	String	AWS S3 bucket name to use for Terraform state. See note
tf_state_bucket_destroy	Boolean	Force purge and deletion of S3 bucket defined. Any file contained there will be destroyed. tf_stack_destroy must also be true. Default is false.

---

Domains and certificates

Name	Type	Description
aws_r53_domain_name	String	Define the root domain name for the application. e.g. bitovi.com'.
aws_r53_sub_domain_name	String	Define the sub-domain part of the URL. Defaults to aws_resource_identifier.
aws_r53_root_domain_deploy	Boolean	Deploy application to root domain. Will create root and www records. Default is false.
aws_r53_enable_cert	Boolean	Set this to true if you wish to manage certificates through AWS Certificate Manager with Terraform. See note. Default is false.
aws_r53_cert_arn	String	Define the certificate ARN to use for the application. See note.
aws_r53_create_root_cert	Boolean	Generates and manage the root cert for the application. See note. Default is false.
aws_r53_create_sub_cert	Boolean	Generates and manage the sub-domain certificate for the application. See note. Default is false.
aws_r53_additional_tags	JSON	Add additional tags to the terraform default tags, any tags put here will be added to R53 provisioned resources.

---

VPC configuration

Name	Type	Description
aws_vpc_create	Boolean	Define if a VPC should be created. Defaults to false.
aws_vpc_name	String	Define a name for the VPC. Defaults to VPC for ${aws_resource_identifier}.
aws_vpc_cidr_block	String	Define Base CIDR block which is divided into subnet CIDR blocks. Defaults to 10.0.0.0/16.
aws_vpc_public_subnets	String	Comma separated list of public subnets. Defaults to 10.10.110.0/24
aws_vpc_private_subnets	String	Comma separated list of private subnets. If no input, no private subnet will be created. Defaults to <none>.
aws_vpc_availability_zones	String	Comma separated list of availability zones. Defaults to aws_default_region+<random> value. If a list is defined, the first zone will be the one used for the EC2 instance.
aws_vpc_id	String	Existing AWS VPC ID to use. Accepts vpc-### values.
aws_vpc_subnet_id	String	Existing AWS VPC Subnet ID. If none provided, will pick one. (Ideal when there's only one).
aws_vpc_enable_nat_gateway	Boolean	Adds a NAT gateway for each public subnet. Defaults to false.
aws_vpc_single_nat_gateway	Boolean	Toggles only one NAT gateway for all of the public subnets. Defaults to false.
aws_vpc_external_nat_ip_ids	String	Existing comma separated list of IP IDs if reusing. (ElasticIPs).
aws_vpc_additional_tags	JSON	Add additional tags to the terraform default tags, any tags put here will be added to vpc provisioned resources.

---

Action Outputs

Name	Description
aws_vpc_id	The selected VPC ID used.
vm_url	The URL of the generated app.
instance_endpoint	The URL of the generated ec2 instance.
ec2_sg_id	SG ID for the EC2 instance.

Note about AWS resource identifiers

Most resources will contain the tag GITHUB_ORG-GITHUB_REPO-GITHUB_BRANCH to make them unique. Because some AWS resources have a length limit, we shorten identifiers to a 60 characters max string.

We use the Kubernetes style for this. For example, Kubernetes -> k(# of characters)s -> k8s. And so you might see how compressions are made.

For some specific resources, we have a 32 characters limit. If the identifier length exceeds this number after compression, we remove the middle part and replace it with a hash made up of the string itself.

S3 buckets naming

Bucket names can be made of up to 63 characters. If the length allows us to add -tf-state, we will do so. If not, a simple -tf will be added.

Domain and Certificates - Only for AWS Managed domains with Route53

As a default, the application will be deployed and the ELB public URL will be displayed.

If aws_domain_name is defined, we will look up for a certificate with the name of that domain (eg. example.com). We expect that certificate to contain both example.com and *.example.com. Resulting URL will be aws_sub_domain.aws_domain_name

If no certificate is available for aws_domain_name, then set up no_cert to true.

If you want to use an already created certificate, or prefer to manage it manually, you can set up aws_cert_arn. Check the AWS notes for how to find the certificate ARN in AWS.

Setting aws_create_root_cert to true will create this certificate with both example.com and *.example.com for you, and validate them. (DNS validation).

Setting aws_create_sub_cert to true will create a certificate just for the subdomain, and validate it.

⚠️ Be very careful here! Created certificates are fully managed by Terraform. Therefore they will be destroyed upon stack destruction.

To change a certificate (root_cert, sub_cert, ARN or pre-existing root cert), you must first set the no_cert flag to true, run the action, then set the no_cert flag to false, add the desired settings and excecute the action again. (This will destroy the first certificate.)

This is necessary due to a limitation that prevents certificates from being changed while in use by certain resources.

Advanced StackStorm configuration with Ansible vars

This action runs ansible-st2 roles under the hood. You can customize the Ansible configuration by creating a yaml file in your repo. This file will be passed to the Ansible playbook as extra vars. See the Ansible-st2 documentation for a full list of available options.

Here is an example st2_vars.yaml pinning the stackstorm to v3.8.0, installing several packs from StackStorm Exchange and configuring st2.conf with extra settings for garbagecollector:

st2_version: "3.8.0"

# Install specific pack versions from StackStorm Exchange
st2_packs:
  - st2
  - aws=1.2.0
  - github=2.1.3

# https://github.com/StackStorm/st2/blob/master/conf/st2.conf.sample
st2_config:
  garbagecollector:
    # Action executions and related objects (live actions, action output objects) older than this value (days) will be automatically deleted. Defaults to None (disabled).
    action_executions_ttl = 90

Example GHA deployment job referencing the Ansible st2_vars.yaml file:

jobs:
  deploy-st2:
    runs-on: ubuntu-latest
    steps:
    - id: deploy-st2-advanced
      name: Deploy StackStorm with extra Ansible vars
      uses: bitovi/github-actions-deploy-stackstorm@v0.4.2
      with:
        aws_default_region: us-east-1
        aws_access_key_id: ${{ secrets.AWS_ACCESS_KEY_ID}}
        aws_secret_access_key: ${{ secrets.AWS_SECRET_ACCESS_KEY}}
        st2_auth_username: ${{ secrets.ST2_AUTH_USERNAME}}
        st2_auth_password: ${{ secrets.ST2_AUTH_PASSWORD}}
        # Pass the Ansible vars file
        st2_ansible_extra_vars_file: "st2_vars.yaml"

We encourage to keep your infrastructure codified!

Made with BitOps

BitOps allows you to define Infrastructure-as-Code for multiple tools in a central place. This action uses BitOps Docker container with prebuilt deployment tools and Operations Repository Structure to organize the necessary Terraform and Ansible steps, create infrastructure and deploy to it.

Extra BitOps Configuration

You can pass additional BITOPS_ ENV variables to adjust the deployment behavior.

- name: Deploy StackStorm to AWS (dry-run)
  uses: bitovi/github-actions-deploy-stackstorm@v0.4.2
  env:
    # Extra BitOps configuration:
    BITOPS_LOGGING_LEVEL: INFO
    # Extra Terraform configuration:
    # https://bitops.sh/tool-configuration/configuration-terraform/#terraform-bitops-schema
    BITOPS_TERRAFORM_SKIP_DEPLOY: true
    # Extra Ansible configuration:
    # https://bitops.sh/tool-configuration/configuration-ansible/#cli-configuration
    BITOPS_ANSIBLE_DRYRUN: true
  with:
    aws_default_region: us-east-1
    aws_access_key_id: ${{ secrets.AWS_ACCESS_KEY_ID }}
    aws_secret_access_key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
    st2_auth_username: ${{ secrets.ST2_AUTH_USERNAME }}
    st2_auth_password: ${{ secrets.ST2_AUTH_PASSWORD}}

In this example, we instruct BitOps to run a terraform plan instead of terraform apply and to run Ansible in --check mode, additionally, we set the BitOps container logging level to DEBUG.

Future

In the future, this action may support multiple deployment types such as:

• Kubernetes
• Multi-VM

This action is still in its early stages, so we welcome your feedback! Open an issue if you have a feature request.

Contributing

We would love for you to contribute to bitovi/github-actions-deploy-stackstorm. Issues and Pull Requests are welcome!

Provided by Bitovi

Bitovi is a proud supporter of Open Source software.

Need help or have questions?

You can get help or ask questions on Discord channel! Come hangout with us!

Or, you can hire us for training, consulting, or development. Set up a free consultation.