GitHub action to deploy StackStorm to an AWS VM (EC2) with Terraform and Ansible.

• 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

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@main
      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, a VPC with subnets (see aws_create_vpc)

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

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

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.

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.

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.

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@main
      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!

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.

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@main
  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.

In the future, this action may support more cloud providers (via BitOps Plugins like AWS) such as:

• Google Cloud Platform
• Microsoft Azure
• Nutanix
• Open Stack
• VMWare
• etc

This action may also 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.

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

Bitovi is a proud supporter of Open Source software.

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.